Skip to main content

BETSE, the BioElectric Tissue Simulation Engine.

Project description

.. # ------------------( BADGES )------------------
.. image::
:alt: Linux Build Status
.. image::
:alt: Windows Build Status

.. # ------------------( SYNOPSIS )------------------


**BETSE** (**B**\ io\ **E**\ lectric **T**\ issue **S**\ imulation **E**\ ngine)
is an open-source cross-platform `finite volume`_ simulator for 2D computational
multiphysics problems in the life sciences – including electrodiffusion_,
electro-osmosis_, galvanotaxis_, `voltage-gated ion channels`_, `gene regulatory
networks`_, and `biochemical reaction networks`_ (e.g., metabolism). BETSE is
associated with the `Paul Allen Discovery Center`_ at `Tufts University`_ and
supported by a `Paul Allen Discovery Center award`_ from the `Paul G. Allen
Frontiers Group`_.

BETSE is `portably implemented <codebase_>`__ in pure `Python 3`_, `continuously
stress-tested <testing_>`__ with GitLab-CI_ **×** Appveyor_ **+** py.test_, and
`permissively distributed <License_>`__ under the `BSD 2-clause license`_.


BETSEE_ (\ **BETSE E**\ nvironment) is the official open-source cross-platform
graphical user interface (GUI) for BETSE. BETSEE_ wraps the low-level
command-line interface (CLI) bundled with BETSE in a high-level interactive
modelling environment optimized for both new and advanced users alike.

Like BETSE, BETSEE_ is `portably implemented <BETSEE codebase_>`__ in `Python
3`_ and `permissively distributed <License_>`__ under the `BSD 2-clause
license`_. Unlike BETSE, BETSEE_ leverages the industry-standard PySide2_-based
`Qt 5 <Qt_>`_ application framework to deliver a modern scientific workflow.

.. # ------------------( TABLE OF CONTENTS )------------------
.. # Blank line. By default, Docutils appears to only separate the subsequent
.. # table of contents heading from the prior paragraph by less than a single
.. # blank line, hampering this table's readability and aesthetic comeliness.


.. # Table of contents, excluding the above document heading. While the
.. # official reStructuredText documentation suggests that a language-specific
.. # heading will automatically prepend this table, this does *NOT* appear to
.. # be the case. Instead, this heading must be explicitly declared.

.. contents:: **Contents**

.. # ------------------( DESCRIPTION )------------------


BETSE currently supports **Linux**, **macOS**, and **Windows** out-of-the-box.


For new users, BETSE is readily installable as follows:

.. # FIXME: Commented out until we actually have a working Windows installation script.

.. # - Under **Windows 10**:
.. #
.. # #. Install **Ubuntu Linux** via the `Windows Subsystem for Linux (WSL) <WSL_>`__.
.. # #. Open an **Ubuntu Linux terminal.** [#terminal]_
.. # #. Run the following commands in this terminal.
.. #
.. # wget && source betsee_windows_10.bash

.. # FIXME: Create a BETSE-specific installer reduced from this BETSEE installer.

- Under `Ubuntu Linux 16.04 (Xenial Xerus)`_ and newer:

#. Open a **terminal.** [#terminal]_
#. Run the following commands.

.. code:: bash

wget && source betsee_ubuntu_16_04.bash

- Under all other platforms: :sup:`(e.g., macOS, Windows)`

#. Install the **Python 3.x** [#python2_not]_ (e.g., 3.6) variant of
Anaconda_. [#anaconda_not]_
#. Open a **terminal.** [#terminal]_
#. Run the following commands.

#. Install **mandatory dependencies.** [#why_dependencies]_

.. code:: bash

conda install dill
conda install -c conda-forge imageio

#. Install **BETSE.** [#pip3_not]_

.. code:: bash

python3 -m pip install betse

#. (\ *Optional*\ ) Install **recommended dependencies.** While *not*
required for basic usage, the following third-party packages are required
for advanced functionality (e.g., gene regulatory networks, animation
video encoding).

.. code:: bash

conda install -c anaconda graphviz && \
conda install -c conda-forge ffmpeg networkx && \
conda install -c rmg pydot

- (\ *Optional*\ ) Test **BETSE.** Run all modelling phases of a sample
simulation from the current directory.

.. code:: bash

betse try

.. [#terminal]
To open a `POSIX`_\ -compatible terminal under:

- **Windows:**

#. Install **Ubuntu Linux** via the `Windows Subsystem for Linux (WSL) <WSL_>`__.
#. Open an *Ubuntu Linux terminal.*

- **macOS:**

#. Open the *Finder*.
#. Open the *Applications* folder.
#. Open the *Utilities* folder.
#. Open **.

- **Ubuntu Linux:**

#. Type ``Ctrl``\ +\ ``Alt``\ +\ ``t``.

.. [#python2_not]
Do *not* install the **Python 2.7** variant of Anaconda_. BETSE requires
**Python 3.x.**

.. [#anaconda_not]
If you prefer *not* to install Anaconda_, BETSE dependencies are `also
installable <Advanced_>`__ with your platform-specific package manager (e.g.,
Homebrew_ on macOS, APT_ on Ubuntu Linux). Doing so is non-trivial and, if
performed incorrectly, could produce a performance-crippled single-core
installation of BETSE – which would be bad. Anaconda_ suffers no such issues
and is guaranteed to produce a performance-optimized multicore installation
of BETSE on *all* supported platforms – which is good.

.. [#why_dependencies]
Most mandatory dependencies of BETSE (e.g., NumPy_, SciPy_) are already
bundled by default with Anaconda_. Some (e.g., dill_, imageio_) are not.
The latter require manual installation.

.. [#pip3_not]
Always run the ``python3 -m pip`` command to install Python packages into the
active Anaconda_ environment. *Never* run the ``pip`` or ``pip3`` commands,
which incorrectly refer to their non-\ Anaconda_ versions on some platforms
(e.g., macOS), which prevents BETSE from finding packages installed with
these commands – which is bad. The ``python3 -m pip`` command suffers no such
issues and is guaranteed to install packages in a BETSE-aware manner on *all*
supported platforms – which is good.


For developers and advanced users, *any* version of BETSE – including the live
repository and prior stable releases – is manually installable as follows:

#. Install **Python 3.x** and `all dependencies <dependencies_>`__ required by
BETSE. Under:

- **Linux,** install `these dependencies <dependencies_>`__ via your
distribution-specific package manager (e.g., APT_ under Debian-based
distributions). Do *not* use ``pip``.\ [#pip_not]_
- **macOS,** either:

- (\ *Recommended*\ ) Install the **Python 3.x** variant of Anaconda_.
- Or both:

#. Install a third-party package manager (e.g., Homebrew_, MacPorts_).
Apple does *not* provide a package manager out-of-the-box.
#. Install `these dependencies <dependencies_>`__ via that package
manager. Do *not* use ``pip``.\ [#pip_not]_

- **Windows,** install the **Python 3.x** variant of Anaconda_.\ [#windows]_

#. Open a **terminal.**
#. **Download** either:

- **The unstable BETSE repository** as follows:

#. Install Git_.
#. Clone the ``master`` branch of this repository.

.. code:: bash

git clone

#. Prepare for installation.

.. code:: bash

cd betse

- **Any stable BETSE release,** including the most recent, as follows:

#. Visit our `source tarball archive <tarballs_>`__.
#. Click the download icon to the right of the desired release and select
*Download tar.gz*.
#. Extract the downloaded tarball into the current directory.

.. code:: bash

tar -xvzf betse-*.tar.gz

#. (\ *Optional*\ ) Remove this tarball.

.. code:: bash

rm betse-*.tar.gz

#. Prepare for installation.

.. code:: bash

cd betse-*

#. **Install BETSE** either:

- (\ *Recommended*\ ) **Editably,** installing a cross-platform symbolic link
to the current BETSE codebase. Modifications to this code are applied
immediately *without* requiring reinstallation.

.. code:: bash

sudo python3 develop

- **Non-editably,** installing a physical copy of the current BETSE codebase.
Modifications to this code are ignored and thus require reinstallation.

.. code:: bash

sudo python3 install

#. (\ *Optional*\ ) **Test BETSE,** running all modelling phases of a sample
simulation from a new directory.

.. code:: bash

cd /tmp && betse try

.. [#pip_not]
Do *not* install scientific dependencies (e.g., NumPy_, SciPy_) with either
``pip`` or ``easy_install``; doing so typically degrades BETSE to single-core
performance. To optimize BETSE across multiple cores, *always* install these
dependencies with your platform-specific package manager (e.g., Homebrew_,

.. [#windows]
Unlike Linux and macOS, Anaconda_ is (\ *effectively*\ ) required under
Windows. Due to Microsoft's lack of support for `POSIX`_\ -compliant
toolchains, *no* reasonable alternatives for installing multicore-aware
scientific dependencies exist.


BETSE itself provides the ``betse`` command, a low-level command line interface
(CLI) optimized for non-interactive scripting (e.g., for implementing massively
parallel `genetic algorithms`_). See the following external documents for
detailed usage instructions – complete with explanatory examples, sample plots,
and ample screenshots:

- Official `BETSE 0.4 documentation`_. (\ *PDF format; 72 pages.*\ )
- Official `BETSE 0.3 documentation`_. (\ *PDF format; 77 pages.*\ )

Alternately, our sister project BETSEE_ provides the ``betsee`` command, a
high-level graphical user interface (GUI) optimized for interactive


BETSE simulates biorealistic electrochemical phenomena in `gap junction`_\
-networked 2D cellular collectives. To predict `bioelectric patterns
<bioelectricity_>`__ and their spatio-temporal dynamics, BETSE:

- Models `ion channel`_ and `gap junction`_ activity.
- Tracks changes in ion concentration and net ionic charge.
- Calculates endogenous voltages and currents.
- Accepts simulation parameters, variables, and options as human-readable,
well-commented configuration files in YAML_ format.
- Exports simulation results to a variety of output formats, including:

- Publication-quality:

- Plots, charts, and animations driven by Matplotlib_, the industry
standard for open-source plot visualization.
- `Directed graphs`_ (i.e., networks) driven by Graphviz_, the industry
standard for open-source graph visualization.

- Internet-friendly compressed video driven by any of various popular
open-source video encoders, including FFmpeg_, Libav_, and MEncoder_.
- Post-processable tabular data (e.g., `comma-separated values (CSV)
<comma-separated values_>`__).

- Imports bitmask images defining the shapes of:

- Cell clusters.
- Cell cluster regions localizing `ion channel`_ activity, typically
signifying disparate types of adjacent tissue.

To assemble simple concepts into complex simulations, BETSE supplies a richly
configurable, highly scalable biological toolset consisting of:


Simulations may enable arbitrary combinations of the principal ions implicated
in bioelectrical signaling – including:

- Sodium_ (*Na*\ :sup:`+`).
- Potassium_ (*K*\ :sup:`+`).
- Chloride_ (*Cl*\ :sup:`-`).
- Calcium_ (*Ca*\ :sup:`2+`).
- Hydrogen_ (*H*\ :sup:`+`).
- `Anionic proteins`_ (*P*\ :sup:`-`).
- Bicarbonate_ (*HCO*\ :sup:`-`\ :sub:`3`).

Ion Channels

Individual cells in simulations may enable arbitrary combinations of
`voltage-gated ion channels`_, each implementing the `Hodgkin-Huxley (HH)
formalism`_ with experimentally-derived parameters sourced from reputable
`knowledge-based systems`_ (e.g., Channelpedia_). Explicitly supported channel
types include:

- HCN1_, HCN2_, and HCN4_.
- `L-type Ca`_, `T-type Ca`_, and |P/Q-type Ca|_.
- Kir2.1_.
- Kv1.1_, Kv1.2_, Kv1.5_. Kv3.3_, and Kv3.4_.
- Nav1.2_, Nav1.3_, and Nav1.6_.
- `Leak <leak channels_>`__ and `ligand-gated channels`_, including:

- |Calcium-gated K+ channels|_.

Custom ion channels parametrized by user-selected constants may be trivially
defined in the same manner (e.g., via a YAML_\ -formatted configuration file).

Ion Pumps and Exchangers

For fine-grained control over cell dynamics, notable ion pumps and exchangers
may also be selectively enabled – including:

- |Ca2+-ATPase|_.
- |H+/K+-ATPase|_.
- |Na+/K+-ATPase|_.
- V-ATPase_.

Custom ion pumps and exchangers parametrized by user-selected constants may be
trivially defined in the same manner (e.g., via a YAML_\ -formatted
configuration file).

Extracellular Space

Cells form interconnected intracellular networks via voltage-sensitive `gap
junction connections <gap junction_>`__ embedded within an `extracellular
environment`_, maintained by `tight junctions`_ at the cell cluster periphery.
Simulation of this environment enables exploration of `local field
potentials`_, `transepithelial potential`_, and `ephaptic coupling`_ between

Biological Networks

Simulation of `gene regulatory <gene regulatory networks_>`__ and `biochemical
reaction networks`_ at both the cellular and mitochondrial level supports deep
spatial analysis of otherwise intractable biological processes. Metabolism,
disease, aging, and other `genetic <genetics_>`__ and `epigenetic
<epigenetics_>`__ phenomena commonly associated with quasi-`Big Data`_ are all
valid targets for exhaustive study with BETSE.

To integrate these potent control systems with bioelectrical signaling, the
`activity <enzyme activity_>`__-modulated interaction between `gene products`_
and similar biochemicals is fully integrated with `ion channels <ion
channel_>`__, `ion pumps`_, and `gap junctions`_.


BETSE is peer-reviewed software receiving continual evidence-based scrutiny.
Simulation output is reproducibly synchronized with experimental observations on
`membrane permeability`_, `resting potential`_, ion concentration, and similar
real-world biophysical quantities. Predictable outcomes have been demonstrated
for such well-known cases as:

- `Transmembrane voltage changes <transmembrane voltage_>`__ on perturbations
to single cell membrane states and environmental ion concentrations.
- `Transepithelial potential differences (TEPD) <transepithelial
- Bioelectrical signals at large-scale cellular wound sites.

For details, see our recently published `introductory paper <Reference_>`__.


BETSE is open-source software `released <LICENSE>`__ under the permissive `BSD
2-clause license`_.


BETSE is formally described in our `introductory paper <2016 article_>`__.
Third-party papers, theses, and other texts leveraging BETSE should (ideally)
cite the following:

`Pietak, Alexis`_ and `Levin, Michael`_, 2016. |2016 article name|_
|2016 journal name|_ *4*\ (55). :sup:`DOI: 10.3389/fbioe.2016.00055`

Subsequent papers expanding the BETSE architecture with additional theory,
experimental results, and comparative metrics include:

`Pietak, Alexis`_ and `Levin, Michael`_, 2017. |2017 article name|_
|2017 journal name|_ *14*\ (134), p.20170425. :sup:`DOI:

.. # FIXME: Add an image thumbnail above displaying the cover image selected by
.. # the prior journal for that edition's cover article.


BETSE comes courtesy a dedicated community of `authors <author list_>`__ and
contributors_ – without whom this project would be computationally impoverished,
biologically misaligned, and simply unusable.

**Thanks, all.**

See Also

For prospective users:

- `Installation <dependencies_>`__, detailing BETSE's installation with
exhaustive platform-specific instructions.

For prospective contributors:

- `Development <doc/md/>`__, detailing development of the BETSE
codebase – philosophy, workflow, and otherwise.
- `Testing <doc/md/>`__, detailing testing of the BETSE codebase –
`continuous integration`_, manual testing, and otherwise.
- `Freezing <doc/md/>`__, detailing conversion of the BETSE codebase
into redistributable platform-specific executable binaries.

.. # ------------------( LINKS ~ betse )------------------
.. _author list:
.. _codebase:
.. _contributors:
.. _dependencies:
.. _testing:
.. _tarballs:

.. # ------------------( LINKS ~ betse : docs )------------------
.. _BETSE 0.4 documentation:
.. _BETSE 0.3 documentation:

.. # ------------------( LINKS ~ betsee )------------------
.. _BETSEE codebase:

.. # ------------------( LINKS ~ academia )------------------
.. _Pietak, Alexis:
.. _Levin, Michael:
.. _Channelpedia:
.. _Paul Allen Discovery Center:
.. _Paul Allen Discovery Center award:
.. _Paul G. Allen Frontiers Group:
.. _Tufts University:

.. # ------------------( LINKS ~ paper ~ 2016 )------------------
.. _2016 article:

.. |2016 article name| replace::
**Exploring instructive physiological signaling with the bioelectric tissue
simulation engine (BETSE).**
.. _2016 article name:

.. |2016 journal name| replace::
*Frontiers in Bioengineering and Biotechnology,*
.. _2016 journal name:

.. # ------------------( LINKS ~ paper ~ 2017 )------------------
.. |2017 article name| replace::
**Bioelectric gene and reaction networks: computational modelling of genetic, biochemical and bioelectrical dynamics in pattern regulation.**
.. _2017 article name:

.. |2017 journal name| replace::
*Journal of The Royal Society Interface,*
.. _2017 journal name:

.. # ------------------( LINKS ~ science )------------------
.. _bioelectricity:
.. _biochemical reaction networks:
.. _electrodiffusion:
.. _electro-osmosis:
.. _enzyme activity:
.. _ephaptic coupling:
.. _epigenetics:
.. _extracellular environment:
.. _finite volume:
.. _galvanotaxis:
.. _gap junction:
.. _gap junctions:
.. _gene products:
.. _gene regulatory networks:
.. _genetics:
.. _Hodgkin-Huxley (HH) formalism:
.. _local field potentials:
.. _membrane permeability:
.. _resting potential:
.. _tight junctions:
.. _transmembrane voltage:
.. _transepithelial potential:

.. # ------------------( LINKS ~ science : ions )------------------
.. _anionic proteins:
.. _bicarbonate:
.. _calcium:
.. _chloride:
.. _hydrogen:
.. _sodium:
.. _potassium:

.. # ------------------( LINKS ~ science : channels )------------------
.. _ion channel:
.. _leak channels:
.. _ligand-gated channels:
.. _voltage-gated ion channels:

.. |calcium-gated K+ channels| replace::
Calcium-gated K\ :sup:`+` channels
.. _calcium-gated K+ channels:

.. # ------------------( LINKS ~ science : channels : type )------------------
.. _HCN1:
.. _HCN2:
.. _HCN4:
.. _Kir2.1:
.. _Kv1.1:
.. _Kv1.2:
.. _Kv1.5:
.. _Kv3.3:
.. _Kv3.4:
.. _Nav1.2:
.. _Nav1.3:
.. _Nav1.6:
.. _L-type Ca:
.. _T-type Ca:

.. |P/Q-type Ca| replace:: :sup:`P`\ /\ :sub:`Q`-type Ca
.. _P/Q-type Ca:

.. # ------------------( LINKS ~ science : pumps : type )------------------
.. _ion pumps:

.. # ------------------( LINKS ~ science : pumps : type )------------------
.. _V-ATPase:

.. |Ca2+-ATPase| replace:: Ca\ :sup:`2+`-ATPase
.. _Ca2+-ATPase:

.. |H+/K+-ATPase| replace:: H\ :sup:`+`/K\ :sup:`+`-ATPase
.. _H+/K+-ATPase:

.. |Na+/K+-ATPase| replace:: Na\ :sup:`+`/K\ :sup:`+`-ATPase
.. _Na+/K+-ATPase:

.. # ------------------( LINKS ~ science : computer )------------------
.. _Big Data:
.. _comma-separated values:
.. _continuous integration:
.. _directed graphs:
.. _genenic algorithms:
.. _knowledge-based systems:

.. # ------------------( LINKS ~ os : linux )------------------
.. _APT:
.. _POSIX:
.. _Ubuntu:
.. _Ubuntu Linux:
.. _Ubuntu Linux 16.04 (Xenial Xerus):

.. # ------------------( LINKS ~ os : macos )------------------
.. _Homebrew:
.. _MacPorts:

.. # ------------------( LINKS ~ os : windows )------------------
.. _WSL:

.. # ------------------( LINKS ~ software )------------------
.. _Anaconda:
.. _Appveyor:
.. _BSD 2-clause license:
.. _dill:
.. _FFmpeg:
.. _Git:
.. _GitLab-CI:
.. _Graphviz:
.. _imageio:
.. _Libav:
.. _Matplotlib:
.. _NumPy:
.. _MEncoder:
.. _Python 3:
.. _py.test:
.. _SciPy:
.. _YAML:

.. # ------------------( LINKS ~ software : pyside2 )------------------
.. _PySide2:
.. _PySide2 5.6:
.. _PySide2 installation:
.. _PySide2 PPA:
.. _Qt:
.. _Qt 5.6:

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
betse-0.6.0-py3-none-any.whl (1.9 MB) Copy SHA256 hash SHA256 Wheel py3
betse-0.6.0.tar.gz (1.5 MB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page