BioFVM: an open source Finite Volume Method for Biological Problems
#BioFVM survey: What would be the most useful next feature?https://t.co/tLlIz2omjB #opensource #biotransport
— Paul Macklin (@MathCancer) August 18, 2016
Introduction
Many biological problems require solving for secretion, diffusion, uptake, and decay of multiple substrates in three dimensions. While many codes have been written to tackle this problem (particularly outside of biology), they often are lacking in one or more areas:
- They can only solve for transport of one or two diffusing species. They are not vectorized to take advantage of modern CPU capabilities (e.g., SIMD, SSE).
- They cannot solve on large 2D or 3D domains. They are not parallelized to take advantage of modern multicore desktop processors (e.g., using OpenMP or multithreading).
- They are parallelized, but primarily for large supercomputers or clusters using MPI, and do not easily run on desktop computers and workstations.
- They use an explicit time stepping, which requires very restrictive time steps and cannot scale to large problems.
- They use implicit steppings that require complex (iterative) matrix inversions.
- They are not open source and cannot be easily modified or validated.
- They have complex dependencies and cannot easily be installed on multiple platforms.
Project goals Back to top
BioFVM aims to create a code that makes large-scale transport solvers accessible to desktop computing:
- Scalable (1): Capable of solving on at least 1 million voxels on modern quad-core desktops.
- Scalable (2): Capable of solving for transport of at least 5 diffusing substrates on modern quad-core desktops.
- Tailored to biological problems: Accelerated for typical biological, cell-centered and bulk secretion/uptake/reaction functions.
- Open source and cross-platform compatible: Use standard, compliant C++ (targeting GCC and Intel C++ Compiler) with minimal external dependencies.
- Simplicity (1): Try simple algorithms before complicated algorithms. This speeds up progress, and it makes the code more robust, easier to parallelize, and simpler to maintain.
- Simplicity (2): When possible, don't use an entire library for the sake of one or two functions. It may not be worth the installation and dependency headaches, especially across platforms. Try to keep the code as self-contained as possible.
- Iterative progress: The first release will focus on getting good performance with reasonable accuracy; later releases will improve accuracy, increase performance, and add new capabilities.
What's NewBack to top
August 19, 2017: We just released version 1.1.6, which includes bugfixes and improvements to how Dirichlet conditions are handled. Also, initialize_microenvironment() no longer overrides user choices if they set up the names and parameter values for densities.
July 19, 2017: We just released version 1.1.5, which includes compatibility updates for PhysiCell, minor bug fixes, and easier initialization functions.
July 25, 2016: We just released version 1.1.4, which includes compatibility updates for PhysiCell. Many thanks to Ahmadreza Ghaffarizadeh for all the contributions and hard work!
July 23, 2016: We just released version 1.1.3, which fixes bugs in the Dirichlet node functions.
July 12, 2016: SourceForge.net, which hosts our project files, seems to be having a major outage. We have updated this site to include links to alternate download sites, where you can still download the code.
July 1, 2016: We just released version 1.1.2, which fixes a cross-platform compatibility bug in the TIC(), TOC(), RUNTIME_TIC(), and RUNTIME_TOC() functions. These now consistently report wall time across platforms. The release also includes a new, easy interface to the C++11 uniform random number distribution, and some nifty functions to compute the mean and variance of a vector of doubles.
March 20, 2016: We just released version 1.1.1, which updates compatibility with MultiCellDS (multicellular data standard), fixes a few bugs, and upgrades to pugixml 1.7 (for greater XML read/write performance).
February 24, 2016: We just released version 1.1.0, which saves data in MultiCellDS (multicellular data standard) format, and includes Matlab functions to read the data. We also changed to a BSD license for better GPL v2 compatibility.
January 22, 2016: We just released version 1.0.3, which provides a template project that should be very helpful for anybody just getting started. It also has matlab files for reading and plotting data.
December 12, 1015: The BioFVM method paper is now publicly available (free and open access) at Bioinformatics. Here's the link:
A. Ghaffarizadeh, S.H. Friedman, and P. Macklin. BioFVM: an efficient, parallelized diffusive transport solver for 3-D biological simulations. Bioinformatics, 2015.
Open access download: click here.
December 4, 1015: We just released version 1.0.2, which has significant peformance improvements for cell-based sources and sinks. Also, the main method paper was accepted for publication in Bioinformatics. We'll post an updated citation here once it's available.
Method, accuracy, and performance Back to top
We use operator splitting to divide complicated PDEs into series of simpler ODEs and a diffusion-decay PDE. To solve the diffusion-decay part, we use locally one-dimensional methods that can be solved efficiently and directly with the Thomas algorithm. All algorithms use implicit time steppings for absolute stability. Wherever possible, we use operator overloading, pre-allocation, and pre-computation to minimize relatively slow memory-bound operations. We use OpenMP to parallelize key operations in the ODE and PDE solvers. (e.g., we solve all x-direction diffusion problems with individual Thomas solvers in parallel.) Further technical details can be found in the supplementary materials of Ghaffarizadeh et al. (2016).
In testing, BioFVM is stable with first-order accuracy in time and second-order accuracy in space. Its computational cost scales linearly with the number of simulated diffusing species: in tests, simulating 10 substrates requries approximately 2.6 times more computational effort than a single substrate. The cost also scales linearly with the number of voxels (domain size or resolution), and with the number of cells secreting/consuming the substrates. In testing (using Δx = 20µm, Δt = 0.01 min), we find that BioFVM typically can simulate 5 diffusing substrates on 1-10 million voxels accurately and efficiently on a modern Intel i7 rocessor with 16 GB of system memory.
Examples Back to top
Examples are included as a tutorial, which is included in every BioFVM download. Diffusion on a large 3-D domain, convergence tests, and performance tests are part of Ghaffarizadeh et al. (2016). More details will be included here in the near future.
Tutorials Back to top
We have made a series of blog posts at http://MathCancer.org/blog/ to walk users through various aspects of BioFVM, such as setting up g++ and writing a sample project. For a full listing of tutorials, please visit:
http://MathCancer.org/blog/biofvm-tutorials/.
Licensing and disclaimers Back to top
BioFVM Version 1.1.0 and later is licensed under the (3-Clause) BSD License. It is GPL v2 and v3 compatible, and suitable for commercial use in many circumstances.
BioFVM Version 1.0.3 and earlier was licensed under the Apache License (v2.0). Those versions were GPL v3 but not GPL v2 compatible. Commercial users of those versions should contact us for alternative licensing.
BioFVM is an academic/scientific code, and it should not be used as the basis for individual medical decisions. (That's what peer review, clinical trials, and FDA oversight are for!) Always consult your physician when making medical decisions.
Downloads Back to top
Software
BioFVM is available for download at SourceForge. Each download includes a tutorial and code examples. If the download links are broken (e.g., due to an outage at SourceForge), use the alternate download link.
Most recent versions
| Version | Release Date | Download link |
|---|---|---|
| 1.1.6 | 19 August 2017 | http://bit.ly/2iiiRJg [sf.net] |
| Notes: Bugfixes and improvements for Dirichlet nodes and initialization functions. | ||
| 1.1.5 | 19 July 2017 | http://bit.ly/2uNN3Bk [sf.net] |
| Notes: Updates for compatibility with PhysiCell, bug fixes, and easier initialization functions. | ||
| 1.1.4 | 25 July 2016 | http://bit.ly/29VH3wm [sf.net] |
| Notes: Updates for compatibility with PhysiCell. | ||
| 1.1.3 | 23 July 2016 | http://bit.ly/2a90KAi [sf.net] |
| Notes: Bugfixes to the Dirichlet functions. | ||
| 1.1.2 | 1 July 2016 | http://bit.ly/298u365 [sf.net] |
| Notes: Bugfixes to the stopwatch functions, new uniform random number functions. | ||
| 1.1.1 | 20 March 2016 | http://bit.ly/1qpSLCG [sf.net] |
| Notes: Updated MultiCellDS write support, bug fixes, and upgrade to pugixml 1.7. | ||
| 1.1.0 | 23 February 2016 | http://bit.ly/1KKgaID [sf.net] |
| Notes: MultiCellDS write support, change to BSD license for GPL v2 compatibility. | ||
| 1.0.3 | 21 January 2016 | http://bit.ly/1nd05jp [sf.net] |
| Notes: New template project, matlab source for reading and plotting data, minor bug fixes. | ||
| 1.0.2 | 4 December 2015 | http://bit.ly/1lD98JO [sf.net] |
| Notes: Performance improvements for cell-based sources/sinks. | ||
| 1.0.1 | 6 November 2015 | http://bit.ly/1PfXVLP [sf.net] |
| Notes: Minor bugfixes. No effect on scientific results. | ||
| 1.0.0 | 16 October 2015 | http://bit.ly/1GKVtEK [sf.net] |
| Notes: First public release | ||
Documentation
- BioFVM Method Paper:
- Ghaffarizadeh et al. (2016) published the original version of BioFVM.
- BioFVM Method Paper: Appendix
- The appendix to Ghaffarizadeh et al. (2016) includes a description of the algorithms and optimizations, convergence testing, and performance testing.
- Tutorials
- A user tutorial with several examples is included with every BioFVM download.
We anticipate writing further tutorials and walk-throughs on the MathCancer blog over the next few months.
Support Back to top
For support, please see the support ticket tracker or contact Paul Macklin. Note that each BioFVM download includes a tutorial and code samples.
If you plan to use BioFVM in a grant proposal, please consider including Paul Macklin as a consultant for more dedicated support.
How to Cite BioFVM Back to top
If you use BioFVM in your project, please cite BioFVM and the version number, such as below:
We solved the diffusion equations using BioFVM (Version 1.1.6) [1]
[1] A. Ghaffarizadeh, S.H. Friedman, and P. Macklin, BioFVM: an efficient parallelized diffusive transport solver for 3-D biological simulations, Bioinformatics 32(8):1256-8, 2016.
DOI: 10.1093/bioinformatics/btv730.
The paper can be downloaded (free; open access) at Bioinformatics. Click here to import the paper into your citation manager (e.g., BibTeX, EndNote, Zotero).
Some publications and projects that cite BioFVM
-
A. Ghaffarizadeh, S.H. Friedman, and
P. Macklin, BioFVM: an efficient parallelized diffusive transport solver
for 3-D biological simulations, Bioinformatics 32(8):1256-8, 2016.
DOI: 10.1093/bioinformatics/btv730.
Additional topics Back to top
Related Projects
- PhysiCell: Our lab's physics-based agent-based simulator uses BioFVM
for simulating the microenvironment.
Link: PhysiCell.MathCancer.org - MultiCellDS: BioFVM will use the MultiCellDS data format once released.
As the first major continuum code to commit to the standard, our data structures
should influence the structuring of microenvironment data elements in the standard.
Link: MultiCellDS.org
