PHOEBE 2.0 Documentation

2.0 Docs

Next: 1. General Concepts

Getting Started

The PHOEBE 2.0 release aims to provide fully-tested functionality that matches that of the legacy PHOEBE 1.0 (light curve and radial velocity forward models of binary star systems) but with improved precision and a python interface.

Although we have attempted to test as thoroughly as possible, please continue to be skeptical of all results and report any issues or bugs or any documentation issues or bugs.

Below we provide installation instructions, tutorials and example scripts for a facilitated experience with PHOEBE.

Supported Physics (from PHOEBE 1.0)

  • detached and semi-detached (since 2.0.5) roche binaries
  • keplerian orbits (including eccentric orbits with volume conservation)
  • passbands/atmospheres
  • limb darkening
  • gravity darkening
  • reflection (heating without redistribution)
  • finite integration time via oversampling
  • circular spots
  • contact systems (to mimic WD)

New Physics (not in PHOEBE 1.0)

  • Doppler boosting
  • single rotating stars
  • Lambert scattering

Unsupported Physics (from PHOEBE 1.0)

PHOEBE 2.0 can not yet handle:

  • full support for contact systems
  • X-ray binaries

Unsupported Convenience Functionality

  • fitting (planned future development)
  • GUI (in development)
  • data in magnitudes (dropping support - convert manually)
  • data in phases (dropping support - but function provided to convert during import)

Planned Physics Support

More advanced physics can be found in the PHOEBE 2.0-alpha releases and will be ported to future official releases as soon as they can be tested robustly.

Planned future features include:

  • heat redistribution (in progress)
  • triple and N-body systems (in progress)
  • advanced overcontact models (in progress)
  • N-body dynamics (in development)
  • misaligned binaries (in development)
  • pulsations (in development)
  • bayesian (MCMC) fitting (in development)
  • synthetic spectra (planning)
  • synthetic eclipse timing variations (ETVs) (planning)
  • synthetic interferometry (planning)

Download and Installation


Note for mac users: it is suggested to use homebrew to install a parallel version of python. PHOEBE has currently been tested to compile correctly using homebrew on El Capitan.

The C++ code in PHOEBE requires a compiler that supports C++11, either of the following should build correctly:

  • g++5 (or newer)
  • clang3.3 (or newer)

Note for Ubuntu 14.04 users: g++5 is not installed by default. You’ll likely need to to do the following in order to install PHOEBE:

sudo add-apt-repository ppa:ubuntu-toolchain-r/test
sudo apt-get install g++-5 gcc-5 libstdc++-5-dev
export CXX=g++-5

PHOEBE requires python 2.7+ (not yet fully tested on python 3.x) with the following packages:

  • python-dev or python3-dev (Python.h needed to compile C-sources)
  • numpy (1.10+)
  • scipy
  • astropy (1.0+)

Suggested packages (required for some optional but commonly used features):

  • matplotlib (suggested for plotting)
  • sympy (for more flexible constraints)

From PIP

Installing PHOEBE from PIP is probably the easiest. To install the latest version:

pip install phoebe

To update a previous installation:

pip install -U phoebe

And to uninstall:

pip uninstall phoebe

If pip gives any problems automatically installing dependencies, install them manually first:

pip install numpy scipy astropy matplotlib

If pip cannot build the C-sources, make sure you have Python.h headers for the correct version of Python, by installing python-dev or python3-dev via your package manager. For debian systems, the following should work:

sudo apt-get install python-dev

Please check the version of PHOEBE you have installed to make sure you are using the corresponding version of the documentation. You can check the version once PHOEBE is imported via phoebe.__version__

Virtual Environments

If installing in a virtual environment, PHOEBE sets the matplotlib backend to ‘TkAgg’ instead of ‘Agg’ by default. To override this, set the backend yourself before importing PHOEBE. To use ‘TkAgg’, you may need to have python-tk installed on your system. See for more information.

To create a virtual environment and install PHOEBE, do the following, replacing “<myphoebedir>” with your (perferably empty or not existing) directory of choice:

pip install virtualenv
virtualenv <myphoebedir>
source <myphoebedir>/bin/activate
pip install numpy scipy astropy matplotlib phoebe

To leave the virtual environment:


And to destroy the virtual environment permanently:

rm -rf <myphoebedir>

From Source

Download Source Code

To download via the github repository:

git clone --depth=1

Note: developers should exclude the depth=1 to get the entire git history (download size will be larger).


NOTE: PHOEBE 2.0 builds to a python module named ‘phoebe’ which may conflict with the alpha version if you have that installed (but will not conflict with PHOEBE 0.2x, 0.3x, or 1.0). If you do have PHOEBE 2.0-alpha installed, please uninstall before attempting to install PHOEBE 2.0. If you have a previous version of PHOEBE 2.x (including PHOEBE 2.0-beta), installing will overwrite that version (unless you use a virtual environment).

python build
python install --user

or to install system-wide (with root priviliges):

python build
sudo python install


The following additional dependencies are required to run the nosetests:

To run all tests locally on your machine, run the following in the ‘tests’ directory in the source.

python run_tests nosetests

Please report any issues or bugs.


Each of the following tutorials builds upon previous tutorials, so it will be most efficient to work through them sequentially at first. However, each should run independently, so feel free to jump in at any point to review a specific concept.

For more specific use-cases, see the example scripts below.

Any of these tutorials can be downloaded as an IPython Notebook or a python script. (see the link at the top of any tutorial). To run these you’ll need PHOEBE installed on your system as well, and for the IPython notebooks you’ll also need IPython (sudo pip install jupyter; sudo apt-get install ipython-notebook). Then simply start the notebook service (ipython notebook [downloaded_tutorial.ipynb]). This will allow you to interact with the tutorial - running it line-by-line and making alterations to see how they change the output.

Advanced Tutorials

The following set of advanced tutorials follow the same format as the tutorials above, but cover individual advanced topics and do not depend on each other.

These all assume comfort with the tutorials listed above, but should not need to be read in any particular order.

Datasets and Observables

The following tutorials aim to both explain the general logic that PHOEBE uses to compute observables as well as explaining the parameters, fields, and options for each observable type.

These aim to be quite thorough and may not be best for light-reading. They expect a comfortable understanding of using PHOEBE and python

Explanations of Individual Parameters

The following tutorials aim to explain the implementation and usage of some of the physical effects that are incorporated in PHOEBE. These explain the relevant parameters and try to demonstrate how they affect the resulting synthetic models, but expect a comfortable understanding of using PHOEBE and python

Example Scripts

These example scripts are generally focussed to show a single advanced feature or a specific science use-case. They are generally less verbose than the tutorials and assume you’re comfortable with the general concepts and syntax of both Python and PHOEBE. Some scripts may be listed under different sections if they fall under multiple categories.

Advanced Plotting

Citing PHOEBE 2.0

If using PHOEBE 2.0, please consider citing the following papers, as appropriate:

See also the full up-to-date list of PHOEBE publications


Q: Is PHOEBE 2.0 backwards compatible with PHOEBE 2.0 alpha releases?

A: Unfortunately, no. We simply learned too much from the alpha-release that we decided that a complete rewrite was needed. However, many of the syntax concepts should be very familiar if you’ve used the frontend in the alpha releases.

Q: Can I speed up plotting in any way?

A: You could try changing your backend, e.g via matplotlib.rcParams['backend'] = 'Agg' but do this before importing Phoebe.

Q: How do I add a custom passband to PHOEBE 2?

A: You will need a table of intensities that you can download from the PHOEBE homepage. Then you should follow the instructions available phoebe.atmospheres.passbands.Passband

Q: Is PHOEBE 2.x Python 3.x ready?

A: PHOEBE has been tested on Python 2.7 with various compilers. We are working towards testing PHOEBE on Python 3.x.

Q: Is it safe to use Phoebe?

A: For the most part, yes. If you do not have sympy installed, then constraints will be evaluated using the ‘eval’ command - which could potentially be dangerous if you blindly open a bundle from an untrusted source. To avoid this, simply install the sympy optional dependency.

Next: 1. General Concepts
Last update: 06/07/2017 11:30 a.m. (CET)