pip install phoebe
PHOEBE stands for PHysics Of Eclipsing BinariEs. PHOEBE is pronounced fee-bee.
PHOEBE 2 is a rewrite of the original PHOEBE code. For most up-to-date information please refer to the PHOEBE project webpage: http://phoebe-project.org
PHOEBE 2.0 is described by the release paper published in the Astrophysical Journal Supplement, Prša et al. (2016, ApJS 227, 29). The addition of support for misaligned stars in version 2.1 is described in Horvat et al. (2018, ApJS 237, 26). Interstellar extinction and support for Python 3 was added in version 2.2 and described in Jones et al. (2020, ApJS 247, 63). Inclusion of a general framework for solving the inverse problem as well as support for the web and desktop clients was introduced in version 2.3 as described in Conroy et al. (2020, ApJS 250, 34), which also removes support for Python 2. PHOEBE 2.4 improves on the geometry and ebai estimators, updates gaussian processes to use either scikit-learn or celerite2, and adds support for submitting compute or solver runs on external servers. These updates and fitting "best practices" will be discussed in Kochoska et al., in prep.
PHOEBE 2 is released under the GNU General Public License v3.
The source code is available for download from the PHOEBE project homepage and from github.
The development of PHOEBE 2 is funded in part by NSF grant #1517474, NSF grant #1909109 and NASA 17-ADAP17-68.
The easiest way to download and install PHOEBE 2 is by using pip (make sure you're using the correct command for pip that points to your python3 installation - if in doubt use something like python3 -m pip install phoebe):
pip install phoebe
To install it site-wide, prefix the pip command with sudo or run it as root.
To download the PHOEBE 2 source code, use git:
git clone https://github.com/phoebe-project/phoebe2.git
To install PHOEBE 2 from the source locally, go to the phoebe2/ directory and issue:
python3 setup.py build
python3 setup.py install --user
To install PHOEBE 2 from the source site-wide, go to the phoebe2/ directory and issue:
python3 setup.py build
sudo python3 setup.py install
Note that as of the 2.3 release, PHOEBE requires Python 3.6 or later. For further details on pre-requisites consult the PHOEBE project webpage.
PHOEBE 2 has a fairly steep learning curve. To start PHOEBE from python, issue:
python
>>> import phoebe
>>>
As of the 2.3 release, PHOEBE also includes a desktop and web client user-interface which is installed independently of the python package here. See the phoebe2-ui repository and phoebe-project.org/clients for more details.
To understand how to use PHOEBE, please consult the tutorials, scripts and manuals hosted on the PHOEBE webpage.
- fix conversion between l3 and l3_frac to account for distance when pblum_mode is absolute
- fix tagged phoebe version in cached bundles to avoid import warning
- fix filtering error when not explicitly passing solver to run_solver
- fix exposing analytic model from lc geometry estimator
- fix phase-sorting when plotting solution from ebai estimator
- add support for differential evolution optimizer solver
- add support for differential corrections optimizer solver
- optimizers: ability to continue runs from previous solutions (for most optimizers)
- improvements to geometry and ebai estimators to use ligeor as a new built-in dependency
- gaussian processes now use celerite2 or scikit-learn instead of celerite
- emcee sampler: additional plotting styles to check for convergence, checks to ensure starting sample is physical, and added ability to continue a previous run from any arbitrary iteration in a previous run
- new support for running jobs on external servers via crimpl
- clarified distinction between chi2 and mle
- fix bug where creating a custom constraint for parameters within features was not correctly identifying the constrained parameter and was raising an error when attempting to set the value of the constraining parameter.
- fix bug where error file was not properly loaded when retrieving error from external job
- remove compiler optimizations that are not portable to ARM architectures
- compare version strings instead of datetime to avoid some systems throwing an error when looking for passband updates.
- see also 2.3.13 release.
- fixes extinction constraint when flipping to solve for Av
- fixes support for astropy 5.0 changes to unit physical types (see also 2.3.51).
- b.save now requires delayed and failed constraints to run before saving.
- introduced in 2.3.55
- fixes installation (on some machines) where m2r is not installed
- fixes handling distributions on array parameters within sample_distribution_collection and run_compute(sample_from).
- updates
distlto convert units with recent changes to astropy. See also the changes in 2.3.51 and 2.3.52. - fixes median introduced in 2.3.52 to act on distribution object instead of just arrays.
- adopting a solution with
adopt_values=Truefor a sampler solver will now adopt the median from the samples rather than the mean, to be consistent with the central values reported by the distributions themselves.
- fixes new run_all_constraints (new in 2.3.51) method to work on array parameters (compute_times/compute_phases).
- fixes parsing the physical type of a unit in latest releases of astropy. Without this fix, some constraints may fail to run.
- implements a new b.run_all_constraints, which is now automatically called when importing from a file in case any constraints were in the failed state.
- rv_geometry: explicitly look for RVs attached to stars (not envelopes, which raised a lookup error).
- run_checks_solver: run compatibility checks between solver and hierarchies. Contact binaries are not supported by lc_geometry or ebai, single stars are not supported by lc_geometry, ebai, or rv_geometry.
- fix remaining cases for flipping requivsumfrac constraint (see 2.3.45 bugfix release for the partial fix for some, but not all, cases)
- migrate from Travis CI to GitHub actions for CI testing
- fixes atmosphere out-of-bounds error caused by mu that should be exactly 0 or 1, but numerically out-of-bounds.
- fixes calculate_lnp to more robustly handle parameter matching for both the constrained and unconstrained case
- fixes default_binary constructor when overriding label of the 'binary' orbit
- fixes typo in ellc backend for the period==1 case
- fixes handling of SB1s (RVs with a single component) in the rv_periodogram estimator
- adds checks to forbid zeros in dataset sigmas
- fixes bug in flipping requivsumfrac constraint for requivratio when requiv of the secondary star is already constrained
- fixes bug in assigning parameter tags when passing function (as kind) to add_component or add_figure.
- fixes silently ignoring component (while calculating residuals, chi2, etc) in an RV dataset in which times are provided, but observational RVs are not.
- improves error messages in calculate_residuals when resulting in no or more than one matches.
- fixes plotting RVs when compute_times is provided instead of times. Previously would raise an error that the 'rvs' parameter could not be found as it is hidden in the dataset.
- fixes handling of default sigmas within LC estimators when no sigmas are provided in the dataset.
- fixes handling of
custom_lnprobability_callablewhen passed torun_solver. Previously an error was raised stating it was not a supported keyword argument and was not passed to the script correctly duringexport_solver.
- fixes bug in increment size in progressbar for optimizers that appears to go past 100% before completion
- when running a forward model sampling from a distribution (or a solution), only allow 10 failed samples per draw before raising an error to prevent getting stuck in an infinite loop if the parameter space is unphysical
- add_compute(overwrite=True) now allows the existing tag to already exist in solutions (in addition to models)
- updates distl to 0.3.1 which includes a fix to treat mvgaussian uncertainties from percentiles like other distribution types
- forces updating kepler's third law constraint when importing a bundle from before 2.3.25 bugfix
- fixes bug where tags on distributions were improperly applied when passing
allow_multiple_matches=True - disables run_compute progressbar within solvers
- fixes typo in description of progress parameter
- fixes bug where running phoebe for the first time within MPI crashes due to each processor attempting to create the passband directory.
- bugfix in equation for converting rotation period/frequency to potential that affects the shapes of rapidly rotating stars with distortion_method of 'rotstar'.
- single stars: implements the missing constraint for requiv_max for single star systems.
- ebai: map phases onto -0.5,0.5 interval after computing phase-shift and sending to ebai
- emcee: cast fitted_uniqueids to list when applying wrap indices for continue_from
- fixes handling of multivariate distributions as priors
- run_compute sample_from: use serial mode when sample_num is 1
- run_compute when passing solution instead of sample_from, default to sample_num=1 if adopt_distributions is False
- export_solver: exclude unneeded distributions/solutions from the exported script to optimize filesize
- export_solver: adds (undocumented until 2.4 release) support for autocontinue
- export_compute: do not require explicitly passing compute if only one exists matching the filter
- calculate_lnp: include_constrained now defaults to True
- fixes version of flask-socketio dependency to remain compatible with desktop client
- ensures path and query string are cast to string
- fixes fitting radial velocities where only one component has observations (SB1 system) and compute_times are provided.
- compute_residuals now returns an empty array when the corresponding times_array is empty, instead of raising an error
- all fitting ld_coeffs. Each coefficient is referenced by index and can be fit or have distributions attached independently. See tutorial for more details.
- also fixes support for custom constraints which can be used to link ld_coeffs between datasets of the same passband, for example.
- do not require passing solution to adopt_solution (when adopting distributions) if only one solution exists
- fix distribution_overwrite_all not defined error
- excludes datasets not supported in fitting (mesh, orb, lp, etc) from forward-model within inverse solvers.
- run_checks_solver now checks for nans in dataset arrays.
- fixes bug where passing overwrite to add_compute or add_solver raised an error if run_compute/run_solver already created a model/solution tagged with that same label.
- allows disabling multiprocessing (or lowering the number of available processors). Multiprocessing is used by default when not within MPI and when calling
run_computewithsample_fromorrun_solverwith solvers that support parallelization. Some installations of multiprocessing on Mac may cause issues, in which case you can now for PHOEBE to run in serial mode. - this introduces new
phoebe.multiprocessing_off(),phoebe.multiprocessing_on(),phoebe.multiprocessing_get_nprocs(), andphoebe.multiprocessing_set_nprocs(n)functions, but the default behavior remains unchanged.
- updates distl to 0.2.0 release which includes support for retaining simultaneous sampling between copies of the same underyling distribution, increased precision on latex formatting of uncertainties, and maintaining labels during unit conversion.
- fix propagating distl distribution objects through constraints to arbitrary depth.
- update Kepler's third law constraint to be distl-friendly (1+q becomes q+1).
- parameter.get_distribution: new argument
delta_if_noneto allow returning a delta function. This is now the default behavior from within b.get/plot_distribution_collection - b.sample_distribution_collection: rename
Nargument tosample_size(but with backwards compatibility support forN). - run_checks_solver now includes a warning if priors contain "around" distributions.
- skip nwalkers vs number of parameters check when continue_from is set
- fallback on twigs when original uniqueids not available (when attempting to continue from a solution loaded into a new bundle, for example)
- wrapping rules for angle parameters fallback on median of last iteration in the available chain when uniqueids do not match as the initializing distribution likely does not exist anymore
- compute vsini from syncpar and pass to RV to enable Rossiter-McLaughlin effect when rv_method='flux-weighted'.
- fix bug in plotting MCMC trace plots when any given chain is all nans.
- fix bug resulting in a nanslice error when phase_bin is enabled within estimators resulting in a single entry in any given bin. Now, sigmas will be ignored within the estimator in these cases with a warning in the logger.
- now correctly maps passbands when using the legacy backend (only affects TESS and Tycho)
- falls back on PHOEBE atmospheres when needing to compute pblums internally for flux scaling prior to calling legacy backend
- from_legacy bugfix in parsing linear limb-darkening coefficients
- export_compute/export_solver: add commment warning against manually editing script
- fixes typo which raised error when rescaling passband-dependent mesh columns
- some systems fail to parse common datetime strings, resulting in inability to import phoebe when checking for available passband updates. This now prints and logs an error message, but does not prevent import.
- checking for available passband updates on import now correctly respects the PHOEBE_ENABLE_ONLINE_PASSBANDS environment variable.
- failed online passbands connection error messages are now only included in the log once (per processor) to avoid spamming the log (but are shown by default when manually calling phoebe.list_online_passbands).
- actually fixes bug (see 2.3.13) that raised internal error when running ebai on an eclipse with width larger than 0.25 in phase. Note that these systems will still return nans as ebai is not well-suited to these systems, but the internal error will no longer occur.
- enables parallelization (per-time or per-dataset) for optimizers.
- fixes estimator.rv_geometry when primary and secondary component have different times.
- fix bug in applying l3_frac within dataset scaling (pblum_mode='dataset-scaled') when using alternate backends.
- fix bug where falling back on twigs when importing a solution on a different bundle failed. It is still suggested to save the bundle and import solutions on the bundle used when calling export_solver.
- fix bug (but not really - see 2.3.18) that raised internal error when running ebai on an eclipse with width larger than 0.25 in phase. Note that these systems will still return nans as ebai is not well-suited to these systems, but the internal error will no longer occur.
- fix bug in the latex labels on plots when converting from multivariate to univariate distributions.
- fix bug where run_checks raised an error for an empty init_from if continue_from was set.
- fix bug where atm parameter was ignored during passband luminosity scaling while using an alternate backend, resulting in an atmosphere out-of-bounds error in some situations.
- stop attempting to query online passbands after three failed attempts to avoid significant time cost otherwise.
- fix bug where datasets were excluded from plotting if not in any models
- fix syntax error in run_checks
- fix small bugs that could raise errors when passing some filter kwargs to
run_solverorsample_distribution_collection
- fix check for presence of observational data during run_checks to only consider datasets with attached gaussian processes (GPs)
- fix length comparison of flux_densities and wavelengths during run_checks
- fixed Gordon extinction coefficient calculation in line with erratum http://dx.doi.org/10.1088/0004-637X/705/2/1320.
- added check to require updating affected-passbands (versions at tables.phoebe-project.org have been updated)
- removed duplicate Passband methods causing ld/ldint passband computations to fail
- fix the latex representation string for
fillout_factor,pot,pot_min, andpot_maxparameters in a contact binary.
- manually include README.md in MANIFEST.in to avoid build errors from pip
- removes m2r as an (unlisted) build-dependency. m2r is only required to build the submission to submit to pypi, but is not required to install or run phoebe locally.
- Add support for inverse problem solvers, including "estimators", "optimizers", and "samplers"
- Add support for attaching distributions (as distl objects) to parameters, including priors and posteriors.
- Add support for web and desktop clients via a light-weight built in
phoebe-server. - Removed support for Python 2 (now requires Python 3.6+)
- Implement optional gaussian processes for light curves
- Implement phase-masking
- Added official support for ellc and jktebop alternate backends
- Per-component and per-dataset RV offsets
- Fixed phasing in time-dependent systems
- Distinction between anomalous and sidereal period in apsidal motion cases
- Extinction parameters moved from per-dataset to the system-level
- Added several new optional constraints
- Overhaul of the run_checks framework
- Updated scipy dependency to 1.7+
- Numerous small bugfixes and enhancements
- fix overriding mesh_init_phi as kwarg to run_compute
- fix pblum computation to not require irrad_method kwarg
- fix bundle representation to exclude hidden parameters
- Improves the detection of g++/gcc version to compare against requirements during setup.
- Add support for interstellar extinction/reddening.
- Support for Python 3.6+ in addition to Python 2.7+.
- Overhaul of limb-darkening with new ld_mode and ld_coeffs_source parameters.
- Overhaul of passband luminosity and flux scaling with new pblum_mode parameter, including support for maintaining color relations between multiple passbands.
- Ability to provide third light in either flux or percentage units, via the new l3_mode and l3_frac parameters.
- Support for computing a model at different times than the observations, via the new compute_times or computes_phases parameter.
- Transition from pickled to FITS passband files, with automatic detection for available updates. The tables can now also be accessed via tables.phoebe-project.org.
- DISABLED support for beaming/boosting.
- Allow flipping Kepler's thrid law constraint to solve for q.
- Require overwrite=True during add_* or run_* methods that would result in overwriting an existing label.
- Constraint for logg.
- Account for time-dependence (dpdt/dperdt) in t0 constraints.
- Future-proof to ignore for passband files with extensions other than ".pb" which may be introduced in future versions of PHOEBE.
- Fixes bug where irradiation was over-optimized and not recomputed as needed for eccentric or misaligned orbits. Introduced in the optimizations in 2.1.6.
- Fixes 'long' location of spots on single stars.
- Fixes treatment of spots on secondary 'half' of contact systems.
- Fixes loading legacy files with a spot that has source of 0 due to a bug in legacy.
- Fixes overriding 'ntriangles' by passing keyword argument to run_compute.
- Fixes the polar rotation axis for RVs in contact systems with non-90 inclinations by re-enabling the alignment (pitch, yaw) constraints and enforcing them to be 0.
- Fixes infinite loop when trying to flip esinw AND ecosw
- Adds ability to flip mass (Kepler's third law) to solve for q
- Fixes bug introduced in 2.1.9 in which out-of-limits constrained parameters in an envelope were being raised before all constraints could resolve successfully.
- Fixes applying t0 when importing legacy dataset which use phase.
- Fixes ignoring other compute options when running checks on kwargs during run_compute.
- Fixes loading legacy datasets which use phase (by translating to time with the current ephemeris).
- Fixes loading legacy datasets with errors in magnitudes (by converting to errors in flux units).
- Fixes plotting RV datasets in which only one component has times (which is often the case when importing from a legacy file).
- Removes ldint from the weights in the computations of RVs and LPs.
- Fixes a bug where parameter limits were not being checked and out-of-limits errors not raised correctly.
- Fixes a bug where certain parameters would cause the meshing algorithm to fail to converge. With this fix, up to 4 additional attempts will be made with random initial starting locations which should converge for most cases.
- Fixes a bug where comparisons between Parameters/ParameterSets and values were returning nonsensical values.
- Comparing ParameterSets with any object will now return a NotImplementedError
- Comparing Parameters will compare against the value or quantity, with default units when applicable.
- Comparing equivalence between two Parameter objects will compare the uniqueids of the Parameters, NOT the values.
- Fixes a bug where automatic detection of eclipses was failing to properly fallback on only detecting the horizon.
- Introduces several other significant optimizations, particularly in run_compute.
- Fixes a bug in hierarchy.get_orbits() for a single star hierarchy which resulted in an error being raised while computing line-profiles.
- This fixes the inversion of the frequency constraint when flipping to solve for period.
- Semi-detached systems could raise an error in the backend caused by the volume being slightly over the critical value when translating between requiv in solar units to volume in unitless/roche units. When this numerical discrepancy is detected, the critical value is now adopted and a warning is sent via the logger.
- All constraints are now executed (by default) in solar units instead of SI. The Kepler's third law constraint (constraining mass by default) failed to have sufficient precision in SI, resulting in inaccurate masses. Furthermore, if the constraint was flipped, inaccurate values of sma could be passed to the backend, resulting in overflow in the semi-detached case.
- Bundles created before 2.1.2 and imported into 2.1.2+ will continue to use SI units for constraints and should function fine, but will not benefit from this update and will be incapable of changing the system hierarchy.
- PHOEBE now detects if its within MPI on various different MPI installations (previously only worked for openmpi).
- Add support for spin-orbit misalignment
- Add support for line profile (LP) datasets
- Switch parameterization from rpole/pot to requiv (including new semi-detached and contact constraints)
- Significant rewrite to plotting infrastructure to use autofig
- Introduction of nparray support within parameters
- Significant rewrite to mesh dataset infrastructure to allow choosing which columns are exposed
- Distinguish Roche (xyz) from Plane-of-Sky (uvw) coordinates
- Ability to toggle interactive constraints and interactive system checks independently
- Implementation of ParameterSet.tags and Parameter.tags
- General support for renaming tags/labels
- Expose pblum for contacts
- Expose per-component r and rprojs for contacts (used to be based on primary frame of reference only)
- Fix definition of vgamma (see note in 2.0.4 release below)
- Remove phshift parameter (see note in 2.0.3 release below)
- Permanently rename 'long' parameter for spots (see note in 2.0.2 release below)
- Numerous other minor bug fixes and improvements
- Set astropy dependency to be >=1.0 and < 3.0 (as astropy 3.0 requires python 3)
- Handle ignoring extraneous spaces when importing a PHOEBE legacy file.
- Previously, after loading from a JSON file, new datasets were ignored by run_compute because the _default Parameters (such as 'enabled') were not stored and loaded correctly. This has now been fixed.
- PS.datasets/components now hides the (somewhat confusing) _default entries.
- unicode handling in filtering is improved to make sure the copying rules from JSON are followed correctly when loaded as unicodes instead of strings.
- Remove unused Parameters from the Bundle
- Improvement in finding the boundary between the two components of a contact system
- Handle missing parameters when importing/exporting so that a Bundle exported to a PHOEBE legacy file can successfully be reimported
- Handle importing standard weight from datasets and converting to sigma
- When requesting unit conversion from the frontend, astropy will now raise an error if the units are not compatible.
- Fixed bug in which importing a PHOEBE legacy file of a semi-detached system failed to set the correct potential for the star filling its roche lobe. This only affects the importer itself.
- Implemented 'critical_rpole' and 'critical_potential' constraints.
- The definition of vgamma in 2.0.* is in the direction of positive z rather than positive RV. For the sake of maintaining backwards-compatibility, this will remain unchanged for 2.0.* releases but will be fixed in the 2.1 release to be in the direction of positive RV. Until then, this bugfix handles converting to and from PHOEBE legacy correctly so that running the PHOEBE 2 and legacy backends gives consistent results.
- Fixed constraint that defines the relation between t0_perpass and t0_supconj.
- Implement new 't0_ref' parameter which corresponds to legacy's 'HJD0'.
- Phasing now accepts t0='t0_supconj', 't0_perpass', 't0_ref', or a float representing the zero-point. The 'phshift' parameter will still be supported until 2.1, at which point it will be removed.
- Inclination parameter ('incl') is now limited to the [0-180] range to maintain conventions on superior conjunction and ascending/descending nodes.
- Fixed error message in ldint.
- Fixed the ability for multiple spots to be attached to the same component.
- Raise an error if attempting to attach spots to an unsupported component. Note: spots are currently not supported for contact systems.
- If using spots, it is important that you use 2.0.2 or later as there were several important bug fixes in this release.
- 'colon' parameter for spots has been renamed to 'long' (as its not actually colongitude). For 2.0.X releases, the 'colon' parameter will remain as a constrained parameter to avoid breaking any existing scripts, but will be removed with the 2.1.0 release.
- Features (including spots) have been fixed to correctly save and load to file.
- Corotation of spots is now enabled: if the 'syncpar' parameter is not unity, the spots will correctly corotate with the star. The location of the spot (defined by 'colat' and 'long' parameters) is defined such that the long=0 points to the companion star at t0. That coordinate system then rotates with the star according to 'syncpar'.
- Definition of flux and luminosity now use ptfarea instead of pbspan. In the bolometric case, these give the same quantity. This discrepancy was absorbed entirely by pblum scaling, so relative fluxes should not be affected, but the underlying absolute luminosities were incorrect for passbands (non-bolometric). In addition to under-the-hood changes, the exposed mesh column for 'pbspan' is now removed and replaced with 'ptfarea', but as this is not yet a documented column, should not cause backwards-compatibility issues.
-
PHOEBE 2.0 is not backwards compatible with PHOEBE 2.0-beta (although the interface has not changed appreciably) or with PHOEBE 2.0-alpha (substantial rewrite). Going forward with incremental releases, every effort will be put into backwards compatibility. The changes and important considerations of the new version will be detailed in the ChangeLog.
-
If upgrading from PHOEBE 2.0-beta or PHOEBE 2.0-alpha, it is necessary to do a clean re-install (clear your build and installation directories), as the passband file format has changed and will not automatically reset unless these directories are manually cleared. Contact us with any problems.
Contact us! Issues and feature requests should be submitted directly through GitHub's issue tracker. Additional questions or feature requests should be submitted via GitHub PHOEBE2 discussions or GitHub PHOEBE2-UI discussions. We are eager to hear from you, so do not hesitate to contact us!