All contributions are welcome! You can mail the developers to get in touch.
We're open to all kind of contributions that improve or extend the ΦFlow library. We especially welcome
- New equations / solvers
- Code optimizations or native (CUDA) implementations.
- Integrations with other computing libraries.
- Bug fixes
ΦFlow is a framework, not an application collection. While we list applications in the demos directory, these should be short and easy to understand.
We recommend you to contact the developers before starting your contribution. There may already be similar internal work or planned changes that would affect how to code the contribution.
To contribute code, fork ΦFlow on GitHub, make your changes, and submit a pull request. Make sure that your contribution passes all tests.
For commits, we use the following tags in the header:
[doc]for documentation updates[ci]for CI configuration changes[build]for changes to the installation[tests]for adding or changing unit tests[demos]for adding or changing demo scripts[Φ]for general changes like version numbers or default imports
If the commit modifies the main codebase (phi/), use one of the following tags:
[vis]for general changes inphi.visas well as changes to any GUI, e.g. dash, widgets, console.[math]for changes tophi.math[backend]for changes specific tophi.math.backendwhich leave thephi.mathAPI untouched.[geom]for changes tophi.geom[field]for changes tophi.fieldexcept Scene[io]for changes to Scenes, data layout[physics]for changes tophi.physics[learning]for non-backend changes tophi.tf,phi.torch
Example commit header: [doc] Improve markdown layout
Commits may be tagged with multiple tags, but this should be used sparingly.
Bugfix commits are tagged with the module to which the fixes are applied.
Style guidelines make the code more uniform and easier to read. Generally we stick to the Python style guidelines as outlined in PEP 8, with some minor modifications outlined below.
Have a look at the Zen of Python for the philosophy behind the rules. We would like to add the rule Concise is better than repetitive.
We use PyLint for static code analysis with specific configuration files for
demos,
tests and the
code base.
PyLint is part of the automatic testing pipeline.
The warning log can be viewed online by selecting a Tests job and expanding the pylint output.
The API documentation for ΦFlow is generated using pdoc. We use Google style docstrings with Markdown formatting.
"""
Function description.
*Note in italic.*
Example:
```python
def python_example()
```
Args:
arg1: Description.
Indentation for multi-line description.
Returns:
Single output. For multi-output use same format as for args.
"""Docstrings for variables are located directly below the public declaration.
variable: type = value
""" Docstring for the variable. """- No line length limit; long lines are allowed as long as the code is easy to understand.
- Code comments should only describe information that is not obvious from the code. They should be used sparingly as the code should be understandable by itself. For documentation, use docstrings instead. Code comments that explain a single line of code should go in the same line as the code they refer to, if possible.
- Code comments that describe multiple lines precede the block and have the format
# --- Comment ---. - Avoid empty lines inside of methods. To separate code blocks use multi-line comments as described above.
- Use the apostrophe character ' to enclose strings that affect the program / are not displayed to the user. Use quotes for text such as warnings.