Generate and manipulate semi-analytic models of planet wakes
Quickstart tutorial »
Documentation »
wakeflow is a Python package primarily for calculating tidally-induced perturbations resulting from a planet embedded in a gas disk. It is an implementation of both the linear theory for planet wake generation (Goldreich and Tremaine 1979) and the non-linear theory of wake propagation (Rafikov 2002) in 2D. wakeflow lets you generate these models by specifying disk and system properties as typically parameterised in the planet formation literature. It also contains additional tools allowing you to:
- Visualise your results
- Create 3D models under some assumptions
- Interface directly with the radiative transfer code
MCFOSTto generate synthetic images of these models - (Planned) Rotate and project your models to create line-of-sight maps of velocity perturbations at some emitting layer
- (Planned) Create analytic predictions for peak velocity maps as found in Calcino et al. 2022
wakeflow is intended to allow both theorists and observers to easily generate models of the interaction between disks and embedded planets, instead of having to run expensive fluid simulations. In particular, wakeflow allows researchers to easily test whether a planet can explain kinematic perturbations observed in some set of disk observations, so-called velocity kinks (see for example Pinte et al. 2018). wakeflow therefore also allows for a fast exploration of disk and planet parameters in order to determine those most likely to recreate observations, before resources are spent on 3D simulations. In addition, wakeflow models may be used with MCFOST to create synthetic images that may be compared directly with observations.
wakeflow may be most easily installed from the Python Package Index (PyPI), or can also be installed from the GitHub repository if you wish to make contributions. Dependencies for wakeflow consist mostly of standard python libraries. We recommend using a package manager such as Anaconda to make your life easier, but this is not required.
The easiest way to install wakeflow is via PyPI, using pip:
pip install wakeflowthat's it!
If you want to contribute to, or modify wakeflow, you should install it from the GitHub repository. After installing the dependencies (see below), simply fork the repo using the button in the top right, and then clone it:
git clone https://github.com/<replace-by-your-username>/wakeflow.gitAlternatively, you may install from source even if you do not wish to edit wakeflow, in which case I would recommend skipping the fork and simply cloning the repo directly:
git clone https://github.com/TomHilder/wakeflow.gitNavigate to the directory it is installed in:
cd wakeflowYou can verify that you are in the correct directory by checking that you see README.md when you run:
lsNow we use pip to create a local and editable install of wakeflow:
python -m pip install -e .Do not forget the dot (.) in the above command, as it tells pip to look in the current working directory (where wakeflow is). The advantage of installing this way is that it places a link to wakeflow in your site-packages folder instead of moving it there. Now when you edit the code in wakeflow/src/wakeflow/ it will edit your installation!
Python packages:
numpymatplotlibastropyscipysetuptoolspyyamltqdmpytest(optional)pytest-cov(optional)pymcfost(optional, only if interfacing with MCFOST)
If you install wakeflow using pip then the required dependencies will be automatically installed.
Please refer to the Quickstart tutorial for the most typical usage of wakeflow including generating models and reading the results. Additional examples of more advanced usage can be found in the Documentation.
wakeflow is automatically unit-tested on Github using Actions and tox. If you have installed wakeflow from source, you may run a local test on your machine provided that you have pytest and pytest-cov installed. Simply navigate to your installation directory and run:
pytestContributions to wakeflow are welcome. If you would like to implement a new feature, please:
- Install using the above installation from source instructions
- Create your Feature Branch (
git checkout -b feature/NewFeature) - Commit your Changes (
git commit -m 'Added some NewFeature') - Push to the Branch (
git push origin feature/NewFeature) - Open a Pull Request
If you have a suggestion that would improve wakeflow but do not have the time or means to implement it yourself, please simply open an issue with the tag "enhancement". If you would like to report a bug, please open an issue with the tag "bug".
Don't forget to give the project a star!
Distributed under the MIT License. See LICENSE.txt for more information.
Please cite Hilder et al. (2023) and Bollati et al. (2021) in any work where wakeflow has been used. Please contact us if wakeflow is useful to you, we welcome any collaboration opportunities.
If you are experiencing issues with wakeflow, please try the following:
- Check the documentation to see if it may be easily resolved
- Open an issue on the repository
- Feel free to contact us directly using the details below
If you are having difficulties installing or using wakeflow, please let us know! We are happy to answer any questions or provide assistance.
Thomas Hilder - [email protected]
Project Link: https://github.com/TomHilder/wakeflow
wakeflow is based on the semi-analytic theory of planets wakes described in Rafikov (2002) and Bollati et al. (2021). The code is partially adapted from analytical kinks which was written by Francesco Bollati, Daniele Fasano and Thomas Hilder, and can be found here.
Additional acknowledgements: