Skip to content

Latest commit

 

History

History
931 lines (666 loc) · 31 KB

INSTALL.rst

File metadata and controls

931 lines (666 loc) · 31 KB
Raw

Installation

BETSE requires:

  • Either Microsoft Windows, Apple macOS, or a Linux distribution. [1]
  • At least Python 3.5 (e.g., 3.5, 3.8). [2]
  • At least 4GB RAM; ideally, at least 16GB RAM. [3]
[1]All other platforms (e.g., Android, FreeBSD) are explicitly unsupported at this time.
[2]All prior Python versions (e.g., Python 2.7, 3.4) are explicitly unsupported as well.
[3]Ergo, BETSE effectively requires a 64-bit system. 32-bit systems impose a so-called "3GB barrier" preventing usage of more than 3—4GB of available RAM, which rarely suffices for even small-scale BETSE simulations.

Contents

Linux

BETSE is installable under modern Linux distributions as follows:

  1. Install Python 3.x. [4] [5]

  2. Open a terminal. [6]

  3. Copy-and-paste these commands into this terminal:

    1. Install BETSE.

      pip3 install betse

    2. [Optional] Test BETSE.

      betse -v try
[4](1, 2, 3, 4) Do not install Python 2.7. BETSE strictly requires Python 3.x.
[5]Most Linux distributions install Python 3.x by default. Since Python ≥ 3.4 installs pip by default, the Python 3.x version of pip should already be installed by default – in theory, anyway.
[6]

To open a terminal under:

  • Ubuntu Linux:
    1. Type Ctrl+Alt+t.

macOS

BETSE is installable under Apple macOS as follows:

  1. Install the Python 3.x [4] (e.g., 3.7) variant of Anaconda. [7]

  2. Open the Finder.

  3. Open the Applications folder.

  4. Open the Utilities folder.

  5. Open Terminal.app.

  6. Copy-and-paste these commands into this terminal:

    1. Enable conda-forge.

      conda config --add channels conda-forge

    2. Install BETSE. [8]

      conda install betse

    3. [Optional] Test BETSE.

      betse -v try
[7]If you prefer not to install Anaconda, BETSE is also `manually installable via third-party package managers for macOS <#macos-homebrew> (e.g., Homebrew, MacPorts). Doing so is non-trivial and, if performed improperly, could produce a performance-crippled single-core installation of BETSE. Anaconda suffers no such issues and is guaranteed to produce a performance-optimized multicore installation of BETSE. We strongly recommend Anaconda – even when you think you know better.
[8]This command installs both the `most recent stable release of BETSE <conda package_>`__ and all mandatory and most optional dependencies of this release. Older stable releases are installable in a similar manner (e.g., conda install betse=0.7.0 for BETSE 0.7.0). All Anaconda packages are kindly hosted by the non-profit conda-forge organization.

Windows

BETSE is installable under Microsoft Windows 10 as follows: [9]

  1. Emulate Ubuntu Linux via the Windows Subsystem for Linux (WSL) bundled with Windows 10.

  2. Open an Ubuntu Linux terminal.

  3. Copy-and-paste these commands into this terminal:

    1. Update the Advanced Package Tool (APT) package cache.
    sudo apt update
    1. Upgrade all previously installed packages.
    sudo apt upgrade
    1. Install Python 3.x.[4]
    sudo apt install python3-pip
    1. Install BETSE.
    pip3 install betse
    1. [Optional] Test BETSE.
    betse -v try
[9]The Windows Subsystem for Linux (WSL) and (thus BETSE itself) is only installable under Windows 10. Under older Windows versions, BETSE may be installed from a virtual Linux guest.

Developers

BETSE also supports Git-based development as follows: [10]

  1. Install Python 3.x. [4]

  2. Install Git.

  3. Register and sign in to a GitLab account.

  4. Fork BETSE via this account.

  5. Click the Clone button on this fork's front page.

  6. Copy the URL given under the Clone with SSH heading.

  7. Open a terminal.

  8. Copy-and-paste these commands from this terminal:

    1. Clone the master branch of this fork into the current directory, replacing {fork_url} below with the URL copied above (e.g., git clone [email protected]:muh_username/betse.git).

      git clone {fork_url}

    2. Install BETSE editably. [11]

      cd betse && pip3 install -e .

    3. Create a new feature branch, replacing {branch_name} below with a string unique to this fork (e.g., git checkout -b muh_branch). [#feature_branch]

      git checkout -b {branch_name}

    4. Change this fork as desired.

    5. Stage and commit these changes.

      git commit -a

    6. Push these changes to the remote copy of your fork hosted at GitLab.

      git push origin {branch_name}

  9. Browse back to BETSE's official project page.

  10. Click the Create merge request button.

  11. Voilà! Instant open-source volunteerism.

[10]For portability, these instructions assume the Python 3.x version of pip has already been installed in a platform-specific manner. While Anaconda may also be leveraged for Git-based development, doing so exceeds the limited scope of these instructions.
[11]An editable installation creates a symbolic link to this clone such that code changes are applied immediately without requiring reinstallation. A standard installation only installs a physical copy of this clone such that code changes are ignored until this clone is reinstalled.
[12]Changes should never be committed directly to the master branch. Changes should only be committed to feature branches (i.e., branches of this clone containing all code changes needed to implement a new feature and/or improve an existing feature). The name of each feature branch must be unique to this clone but is otherwise arbitrary.

Docker

BETSE is also installable into a Docker container, circumventing the need to install BETSE directly into a host operating system. For simplicity, the following instructions assume a modern Linux distribution: [13]

  1. Install Docker.

  2. Instruct the Xauthority security mechanism to ignore hostnames, enabling Docker containers with different hostnames than that of the local host to access the current X11 socket. [14]

    touch /tmp/.docker.xauth && xauth nlist :0 |
    sed -e 's/^..../ffff/' |
    xauth -f /tmp/.docker.xauth nmerge -

  3. Download the latest version of the official Anaconda 3 Docker image and instantiate this image as a new Docker container named betse running an interactive Bash session mounting the X11 socket of the host's current X11 session.

    docker run -it\
    --name betse\
    -v /tmp/.X11-unix:/tmp/.X11-unix\
    -v /tmp/.docker.xauth:/tmp/.docker.xauth\
    -e DISPLAY=$DISPLAY\
    -e XAUTHORITY=/tmp/.docker.xauth\
    continuumio/anaconda3 bash

  4. Copy-and-paste these commands into this container's terminal:

    1. [Optional] Test the X11 connection by running xeyes.

      apt-get update && apt-get install -y x11-apps && xeyes

    2. Download the live version of BETSE into the ${HOME} directory of the current user (i.e., root).

      cd ~ && git clone https://gitlab.com/betse/betse.git

    3. Install BETSE editably.

      cd betse && pip3 install -e .

    4. [Optional] Test BETSE by running a sample simulation.

      cd /tmp && betse try && rm -rf sample_sim

    5. Exit this session.

      exit

To resume the previously instantiated container:

  1. Restart this container.

    docker start betse

  2. Reenter this container by running another interactive Bash session.

    docker attach betse
[13]While Docker is also installable under macOS or Windows, doing so exceeds the limited scope of these instructions.
[14]Thanks to Jürgen Weigert for his observant Stackoverflow answer inspiring this snippet.

Alternative Instructions

Warning

The alternative installation instructions listed below are outdated. Unlike the official instructions above, these unofficial instructions are intended more as inspiration for command-line aficionados than gospel. Copy-and-pasting these instructions into a terminal blindly will yield a broken installation of BETSE in the best case and a broken operating system, terminal, or Python environment in the worst case. There be dragons here.

BETSE is installable with only one or two simple commands on all supported platforms – complete with multicore-aware hardware optimizations. These commands strictly adhere to scientific standards for Python packaging, including the standard pip Python package manager and cross-platform Anaconda Python distribution.

For advanced users preferring to manually install dependencies with platform-specific package managers (e.g., APT), BETSE may also be manually installed in a platform-specific manner. This approach has the obvious advantage of cleanly integrating with existing packaging regimes but the non-obvious disadvantage of typically installing a single-core version of BETSE with no multicore-aware hardware optimizations. That's bad.

Due to the difficulty of manually installing BETSE in a multicore-aware manner, our simple installation instructions are strongly recommended. For completeness, these instructions nonetheless detail the manual approach for several popular package managers.

Linux

BETSE is manually installable with most Linux package managers.

Debian

Under Debian-based Linux distributions (e.g., Linux Mint, Ubuntu), all mandatory dependencies are installable in a system-wide manner as follows:

sudo apt-get install python3-dev python3-dill python3-matplotlib \
    python3-numpy python3-pil python3-pip python3-scipy python3-setuptools \
    python3-six python3-yaml tcl tk

Under some (especially older) Debian-based Linux distributions, the above instructions may not entirely suffice to satisfy all installation-time or runtime requirements. Under these distributions, dependencies may require some form of recompilation, relinking, or reinstallation.

Matplotlib

BETSE requires a fairly recent version of Matplotlib. If the newest version of Matplotlib installed by your distribution is insufficient, the newest version of Matplotlib is installable in a system-wide manner as follows:

sudo apt-get uninstall python3-matplotlib &&
sudo apt-get install gcc gfortran libfreetype6-dev libpng-dev \
    libpython3-all-dev tcl-dev tk-dev &&
sudo pip3 install matplotlib[all]
BLAS and LAPACK

BETSE strongly recommends that optimized (rather than the unoptimized default) implementations of the BLAS and LAPACK APIs for linear algebra be used. While there exist numerous alternatives both open-source (e.g., CBLAS) and proprietary (e.g., MKL), the following instructions assume use of either ATLAS or OpenBLAS.

ATLAS

Automatically Tuned Linear Algebra Software (ATLAS) is the standard baseline for all optimized BLAS and LAPACK implementations. ATLAS is installable in a system-wide manner as follows:

sudo apt-get install build-essential libatlas-base-dev

Note that OpenBLAS and ATLAS cannot be installed at the same time.

OpenBLAS

OpenBLAS is a more performant (but arguably less stable) optimized BLAS and LAPACK implementation. While ATLAS is recommended for new users, experienced users requiring improved performance may benefit from installing OpenBLAS instead. OpenBLAS is installable in a system-wide manner as follows:

sudo apt-get install build-essential libopenblas-dev

Note that OpenBLAS and ATLAS cannot be installed at the same time.

Gentoo

Under Gentoo-based Linux distributions (e.g., Chrome OS, Sabayon), all mandatory and optional dependencies are installable in a system-wide manner as follows:

  1. Install the eselect repository module.

    emerge --ask app-eselect/eselect-repository &&
    mkdir -p /etc/portage/repos.conf

  2. Add and synchronize the raiagent overlay, religiously maintained by a BETSE co-maintainer.

    eselect repository enable raiagent && emerge --sync raiagent

  3. Install both BETSE and BETSEE, our official PySide2-based GUI.

    emerge --autounmask betsee

macOS (Homebrew)

Under Apple macOS, all mandatory dependencies are installable in a system-wide manner with either:

  • [Recommended] Homebrew, an unofficial package manager for macOS. Homebrew provides robust support for features commonly required by BETSE developers, including the capacity to install older rather than merely the newest versions of packages.
  • MacPorts, another unofficial package manager for macOS. MacPorts lacks robust support for features commonly required by BETSE developers, as described above. Since Homebrew and MacPorts install packages into different system directories (i.e., /usr/local for Homebrew, /opt for MacPorts), the two can technically be used on the same system. However, this is generally discouraged. If you currently use and prefer MacPorts, consider adopting the following instructions to use MacPorts rather than Homebrew.

For simplicity, the following instructions assume use of Homebrew:

  1. Register as an Apple Developer. While free, registration requires an existing Apple ID and hence ownership of an existing Apple product. We don't make the awful rules. We only complain about them.

  2. Upgrade your system to the most recently released minor version for your currently installed major version of macOS. For example, if your system is macOS 10.8.3 (Mountain Lion), upgrade to 10.8.5 (Mountain Lion). Homebrew requires recent command-line tools (e.g., clang, gcc), requiring requires recent XCode Command Line Tools (CLT), requiring a recent version of XCode, requiring a recent version of macOS. Provided your system meets the minimum requirements noted above, it should not be necessary to upgrade your system to a newer major version of macOS (e.g., from 10.8.5 to 10.9.5).

  3. Open a terminal window (e.g., by running the pre-bundled Applications/Utilities/Terminal.app application).

  4. If an older version of the XCode Command Line Tools (CLT) has already been installed, manually uninstall the CLT. While XCode itself is safely upgradable merely by installing a new version, the CLT generally is not. You can thank Apple for that.

  5. Download and install the most recent version of XCode available for your version of macOS. While free, this download requires an Apple Developer login.

  6. [Optional] After installing Xcode, perform the following before running Xcode:

  7. Instruct Gatekeeper to implicitly trust Xcode. Gatekeeper is the macOS application security manager. By default, Gatekeeper uselessly verifies Xcode via a labouriously time-consuming and safely skippable bureaucratic process requiring in upwards of twenty minutes on lower-end laptops. Note that verification is not safely skippable for "dubious" applications downloaded from third-party sources.

    $ sudo xattr -d com.apple.quarantine /Applications/Xcode.app

  8. Run Xcode (e.g., by double-clicking Applications/Xcode from the Finder). If you did not instruct Gatekeeper to implicitly trust this application as described above, grab a bag of greasy popcorn and Blade Runner (The Final Cut). You'll need both.

  9. Agree to the Xcode license. This must be done before attempting to run any Xcode-bundled commands from the terminal (e.g., clang, gcc, git).

  10. [Optional] Close Xcode.

  11. Download and install the exact same version of the XCode Command Line Tools (CLT) as the installed version of XCode. Attempting to install an older or newer version of the CLT may superficially succeed but will result in obscure and difficult-to-debug issues on attempting to install dependencies with Homebrew or MacPorts. There are various approaches to installing the correct version of the CLT – some inherently safer than others. Either:

    • [Recommended] Manually download and install the CLT:

      1. Browse to the Apple Developer Downloads site.
      2. Enter xcode into the search bar.
      3. Manually search the resulting hits for the installed version of XCode.
      4. Note the official date of this version's release (e.g., June 12, 2013 for XCode 4.6.3).
      5. Manually search the resulting hits for the most recent version of the CLT preceding this date (e.g., April 11, 2013 for the CLT corresponding to XCode 4.6.3).
      6. Download and install this version.

    • [Not cecommended] Automatically download and install the CLT. While error-prone and hence discouraged, automatically downloading and installing the CLT with Apple-based automation is technically feasible in common edge cases. If your system has been upgraded to both the most recently released minor version of the currently installed major version of macOS and the most recently released version of XCode for that version of macOS, the following command should suffice. If in doubt, prefer the manual approach listed above instead.

      xcode-select –install

  12. Download and install Homebrew. While these dependencies are also technically installable via MacPorts, Homebrew provides significantly more robust support for features of interest to BETSE users. Critically, this includes the capacity to install alternative versions of dependencies rather than merely the newest.

    ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

  13. Manually prepend the current ${PATH} by the absoute paths of all directories to which Homebrew installs packages. To do so permanently, append the following line to the appropriate startup dotfile in your home directory for your preferred shell (e.g., .bashrc for Bash, the default macOS shell).

    export PATH="/usr/local/bin:/usr/local/sbin:${PATH}"

  14. Activate this ${PATH} change. Either:

    • [Recommended] Close the current terminal window and open a new terminal window.

    • [Not recommended] Manually source the modified dotfile: e.g.,

      source ~/.bashrc

  1. [Optional] Inspect your Homebrew installation for potential issues. The following command should report that "Your system is ready to brew." If it does not, consider resolving all reported issues before continuing.

    brew doctor

  2. Install all dependencies.

    brew tap homebrew/python &&
    brew install python3 &&
    pip3 install --upgrade pip setuptools wheel &&
    brew install matplotlib --with-python3 --without-python &&
    brew install numpy --with-python3 --without-python &&
    brew install pillow --with-python3 --without-python &&
    brew install scipy --with-python3 --without-python &&
    brew install libyaml &&
    pip3 install dill pyyaml

Note that Homebrew is a source-based package manager and hence relatively slow. Expect the installation process to require anywhere from several hours to several days, depending on hardware performance. We wish we were kidding.

Note also that these instructions link NumPy against the most optimized multicore implementation of the BLAS and LAPACK APIs available under macOS as of this writing: Apple's Accelerate Framework. No further BLAS or LAPACK configuration is required or recommended.

Optional Dependencies

BETSE optionally leverages (but does not strictly require) the following dependencies where available at runtime:

  • NetworkX >= 1.11, for optionally analyzing BETSE networks.
  • pprofile >= 1.8, for optionally profiling BETSE in a line-granular manner.
  • ptpython >= 0.29, for optionally wrapping the BETSE REPL with an improved interface. By default, the BETSE REPL leverages the stock Python REPL.
  • py.test >= 2.8.0, for optionally running unit tests.
  • PyDot >= 1.0.28 and GraphViz >= 2.38, for optionally visualizing BETSE networks.
  • PyInstaller >= 3.0, for optionally freezing BETSE.
  • UPX (any version), for optionally compressing frozen BETSE executables.

These dependencies are installable as follows.

NetworkX

To optionally analyze networks (e.g., gene regulatory, biochemical reaction), BETSE requires NetworkX, a pure-Python graph theoretic framework. This dependency is installable in a system-wide manner as follows:

  • Under Debian-based Linux distributions (e.g., Linux Mint, Ubuntu):

    $ sudo apt-get install python3-networkx

  • Under all other supported platforms:

    $ pip3 install networkx

pprofile

To optionally profile the BETSE codebase with line-granularity into callgrind-compatible profile files, BETSE requires pprofile, an advanced pure-Python line profiler. This dependency is installable in a system-wide manner as follows:

  • Under all supported platforms:

    $ pip3 install pprofile

ptpython

To optionally wrap the BETSE REPL with an improved interface providing syntax highlighting, multiline editing, autocompletion, and presumably more, BETSE requires ptpython, an advanced pure-Python REPL. This dependency is installable in a system-wide manner as follows:

  • Under all supported platforms:

    $ pip3 install ptpython

py.test

To optionally run tests, BETSE requires py.test, a pure-Python test harness. This dependency is installable in a system-wide manner as follows:

  • Under Debian-based Linux distributions (e.g., Linux Mint, Ubuntu):

    $ sudo apt-get install python3-pytest

  • Under all other supported platforms:

    $ pip3 install pytest

Plugins

While optional, BETSE provides out-of-the-box support for the following third-party py.test plugins:

  • pytest-xdist, parallelizing test runs across all available processors. py.test itself provides no built-in support for parallelization! Since BETSE's test suite is computationally expensive (if not prohibitive), this plugin is a hard prerequisite for sanity preservation.

Contributors are strongly encouraged to install these optional dependencies, which BETSE's test suite will then implicitly detect and set accordingly. These dependencies are installable in a system-wide manner as follows:

  • Under all other supported platforms:

    $ pip3 install pytest-xdist

PyDot + GraphViz

To optionally visualize networks (e.g., gene regulatory, biochemical reaction), BETSE requires both:

  • PyDot, a high-level pure-Python GraphViz wrapper.
  • GraphViz, a low-level C-based graph theoretic visualizer.

These dependencies are installable in a system-wide manner as follows:

  • For PyDot:

    • Under Debian-based Linux distributions (e.g., Linux Mint, Ubuntu):

      $ sudo apt-get install python3-pydot

    • Under all other supported platforms:

      $ pip3 install pydot

  • For GraphViz:

    • Under Debian-based Linux distributions (e.g., Linux Mint, Ubuntu):

      $ sudo apt-get install graphviz

    • Under Apple macOS:

      $ brew install graphviz

PyInstaller

To optionally freezing BETSE, BETSE requires PyInstaller, a non-pure-Python cross-platform command-line utility for freezing Python applications. This dependency is installable in a system-wide manner as follows:

  • Under all supported platforms:

    $ pip3 install pyinstaller

UPX

To optionally compress executables while freezing BETSE, BETSE requires the Ultimate Packer for eXecutables (UPX), a non-Python cross-platform command-line utility for compressing arbitrary executables. This dependency is installable in a system-wide manner as follows:

  • Under Debian-based Linux distributions (e.g., Linux Mint, Ubuntu):

    $ sudo apt-get install upx-ucl

  • Under Apple OS X:

    $ brew install upx