Generate and manipulate semi-analytic models of planet wakes

Quickstart tutorial »
Documentation »

Overview

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 MCFOST to 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.

(back to top)

Installation

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.

PyPI (pip)

The easiest way to install wakeflow is via PyPI, using pip:

pip install wakeflow

that's it!

From source (GitHub)

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.git

Alternatively, 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.git

Navigate to the directory it is installed in:

cd wakeflow

You can verify that you are in the correct directory by checking that you see README.md when you run:

ls

Now 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!

(back to top)

Dependencies

Python packages:

• numpy
• matplotlib
• astropy
• scipy
• setuptools
• pyyaml
• tqdm
• pytest (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.

Usage

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.

(back to top)

Testing

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:

pytest

Contributing

Contributions to wakeflow are welcome. If you would like to implement a new feature, please:

1. Install using the above installation from source instructions
2. Create your Feature Branch (git checkout -b feature/NewFeature)
3. Commit your Changes (git commit -m 'Added some NewFeature')
4. Push to the Branch (git push origin feature/NewFeature)
5. 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!

(back to top)

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

Citing

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.

(back to top)

Getting Help

If you are experiencing issues with wakeflow, please try the following:

1. Check the documentation to see if it may be easily resolved
2. Open an issue on the repository
3. Feel free to contact us directly using the details below

Contact

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 - thil0004@student.monash.edu

Project Link: https://github.com/TomHilder/wakeflow

(back to top)

Acknowledgments

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:

• Img Shields
• Best-README-Template
• Tox
• Tox GH Actions

(back to top)