Skip to content

Latest commit

 

History

History
313 lines (212 loc) · 17.9 KB

CONTRIBUTING.md

File metadata and controls

313 lines (212 loc) · 17.9 KB
Raw

Contributing to pybamm-param

If you'd like to contribute to pybamm-param (thanks!), please have a look at the guidelines below.

If you're already familiar with our workflow, maybe have a quick look at the pre-commit checks directly below.

Pre-commit checks

Before you commit any code, please perform the following checks:

Workflow

We use GIT and GitHub to coordinate our work. When making any kind of update, we try to follow the procedure below.

A. Before you begin

  1. Create an issue where new proposals can be discussed before any coding is done.
  2. Create a branch of this repo (ideally on your own fork), where all changes will be made
  3. Download the source code onto your local system, by cloning the repository (or your fork of the repository).
  4. Install pybamm-param with the developer options.
  5. Test if your installation worked, using the test script: $ python run-tests.py --unit.

You now have everything you need to start making changes!

B. Writing your code

  1. pybamm-param is developed in Python, and makes heavy use of NumPy (see also NumPy for MatLab users and Python for R users).
  2. Make sure to follow our coding style guidelines.
  3. Commit your changes to your branch with useful, descriptive commit messages: Remember these are publicly visible and should still make sense a few months ahead in time. While developing, you can keep using the GitHub issue you're working on as a place for discussion. Refer to your commits when discussing specific lines of code.
  4. If you want to add a dependency on another library, or re-use code you found somewhere else, have a look at these guidelines.

C. Merging your changes with pybamm-param

  1. Test your code!
  2. pybamm-param will have online documentation in ReadTheDocs. To make sure any new methods or classes you added show up there, please read the documentation section.
  3. If you added a major new feature, perhaps it should be showcased in an example notebook.
  4. When you feel your code is finished, or at least warrants serious discussion, run the pre-commit checks and then create a pull request (PR) on pybamm-param's GitHub page.
  5. Once a PR has been created, it will be reviewed by any member of the community. Changes might be suggested which you can make by simply adding new commits to the branch. When everything's finished, someone with the right GitHub permissions will merge your changes into pybamm-param main repository.

Finally, if you really, really, really love developing pybamm-param, have a look at the current project infrastructure.

Coding style guidelines

pybamm-param follows the PEP8 recommendations for coding style. These are very common guidelines, and community tools have been developed to check how well projects implement them.

Flake8

We use flake8 to check our PEP8 adherence. To try this on your system, navigate to the pybamm-param directory in a console and type

flake8

Flake8 is configured inside the file tox.ini, under the section [flake8], allowing us to ignore some errors. If you think this should be added or removed, please submit an issue

When you commit your changes they will be checked against flake8 automatically (see infrastructure).

Black

We use black to automatically configure our code to adhere to PEP8. Black can be used in two ways:

  1. Command line: navigate to the pybamm-param directory in a console and type
black {source_file_or_directory}
  1. Editor: black can be configured to automatically reformat a python script each time the script is saved in an editor.

If you want to use black in your editor, you may need to change the max line length in your editor settings.

Even when code has been formatted by black, you should still make sure that it adheres to the PEP8 standard set by Flake8.

Naming

Naming is hard. In general, we aim for descriptive class, method, and argument names. Avoid abbreviations when possible without making names overly long, so mean is better than mu, but a class name like MyClass is fine.

Class names are CamelCase, and start with an upper case letter, for example MyOtherClass. Method and variable names are lower case, and use underscores for word separation, for example x or iteration_count.

Dependencies and reusing code

While it's a bad idea for developers to "reinvent the wheel", it's important for users to get a reasonably sized download and an easy install. In addition, external libraries can sometimes cease to be supported, and when they contain bugs it might take a while before fixes become available as automatic downloads to pybamm-param users. For these reasons, all dependencies in pybamm-param should be thought about carefully, and discussed on GitHub.

Direct inclusion of code from other packages is possible, as long as their license permits it and is compatible with ours, but again should be considered carefully and discussed in the group. Snippets from blogs and stackoverflow can often be included without attribution, but if they solve a particularly nasty problem (or are very hard to read) it's often a good idea to attribute (and document) them, by making a comment with a link in the source code.

Matplotlib

We use Matplotlib in pybamm-param, but with two caveats:

First, Matplotlib should only be used in plotting methods, and these should never be called by other pybamm-param methods. So users who don't like Matplotlib will not be forced to use it in any way. Use in notebooks is OK and encouraged.

Second, Matplotlib should never be imported at the module level, but always inside methods. For example:

def plot_great_things(self, x, y, z):
    import matplotlib.pyplot as plt
    ...

This allows people to (1) use pybamm-param without ever importing Matplotlib and (2) configure Matplotlib's back-end in their scripts, which must be done before e.g. pyplot is first imported.

Testing

All code requires testing. We use the unittest package for our tests. (These tests typically just check that the code runs without error, and so, are more debugging than testing in a strict sense. Nevertheless, they are very useful to have!)

If you have tox installed, to run unit tests, type

tox -e unit

else, type

python run-tests.py --unit

Writing tests

Every new feature should have its own test. To create ones, have a look at the test directory and see if there's a test for a similar method. Copy-pasting this is a good way to start.

Next, add some simple (and speedy!) tests of your main features. If these run without exceptions that's a good start! Next, check the output of your methods using any of these assert methods.

Running more tests

The tests are divided into unit tests, whose aim is to check individual bits of code (e.g. discretising a gradient operator, or solving a simple ODE), and integration tests, which check how parts of the program interact as a whole (e.g. solving a full model). If you want to check integration tests as well as unit tests, type

tox -e tests

When you commit anything to pybamm-param, these checks will also be run automatically (see infrastructure).

Testing notebooks

To test all example scripts and notebooks, type

tox -e examples # (GNU/Linux and MacOS)
#
python -m tox -e windows-examples # (Windows)

If notebooks fail because of changes to pybamm-param, it can be a bit of a hassle to debug. In these cases, you can create a temporary export of a notebook's Python content using

python run-tests.py --debook examples/notebooks/notebook-name.ipynb script.py

Debugging

Often, the code you write won't pass the tests straight away, at which stage it will become necessary to debug. The key to successful debugging is to isolate the problem by finding the smallest possible example that causes the bug. In practice, there are a few tricks to help you to do this, which we give below. Once you've isolated the issue, it's a good idea to add a unit test that replicates this issue, so that you can easily check whether it's been fixed, and make sure that it's easily picked up if it crops up again. This also means that, if you can't fix the bug yourself, it will be much easier to ask for help (by opening a bug-report issue).

  1. Run individual test scripts instead of the whole test suite:
python tests/unit/path/to/test

You can also run an individual test from a particular script, e.g.

python tests/unit/test_quick_plot.py TestQuickPlot.test_failure

If you want to run several, but not all, the tests from a script, you can restrict which tests are run from a particular script by using the skipping decorator:

@unittest.skip("")
def test_bit_of_code(self):
    ...

or by just commenting out all the tests you don't want to run 2. Set break points, either in your IDE or using the python debugging module. To use the latter, add the following line where you want to set the break point

import ipdb; ipdb.set_trace()

This will start the Python interactive debugger. If you want to be able to use magic commands from ipython, such as %timeit, then set

from IPython import embed; embed(); import ipdb; ipdb.set_trace()

at the break point instead. Figuring out where to start the debugger is the real challenge. Some good ways to set debugging break points are: a. Try-except blocks. Suppose the line do_something_complicated() is raising a ValueError. Then you can put a try-except block around that line as:

try:
    do_something_complicated()
except ValueError:
    import ipdb; ipdb.set_trace()

This will start the debugger at the point where the ValueError was raised, and allow you to investigate further. Sometimes, it is more informative to put the try-except block further up the call stack than exactly where the error is raised. b. Warnings. If functions are raising warnings instead of errors, it can be hard to pinpoint where this is coming from. Here, you can use the warnings module to convert warnings to errors:

import warnings
warnings.simplefilter("error")

Then you can use a try-except block, as in a., but with, for example, RuntimeWarning instead of ValueError. 4. To get more information about what is going on under the hood, and hence understand what is causing the bug, you can set the logging level to DEBUG by adding the following line to your test or script:

pybamm.set_logging_level("DEBUG")

Profiling

Sometimes, a bit of code will take much longer than you expect to run. In this case, you can set

from IPython import embed; embed(); import ipdb; ipdb.set_trace()

as above, and then use some of the profiling tools. In order of increasing detail:

  1. Simple timer. In ipython, the command
%time command_to_time()

tells you how long the line command_to_time() takes. You can use %timeit instead to run the command several times and obtain more accurate timings. 2. Simple profiler. Using %prun instead of %time will give a brief profiling report 3. Detailed profiler. You can install the detailed profiler snakeviz through pip:

pip install snakeviz

and then, in ipython, run

%load_ext snakeviz
%snakeviz command_to_time()

This will open a window in your browser with detailed profiling information.

Documentation

pybamm-param is documented in several ways.

First and foremost, every method and every class should have a docstring that describes in plain terms what it does, and what the expected input and output is.

These docstrings can be fairly simple, but can also make use of reStructuredText, a markup language designed specifically for writing technical documentation. For example, you can link to other classes and methods by writing :class:`pbparam.OptimisationProblem` and :meth:`run()` .

In addition, we write a (very) small bit of documentation in separate reStructuredText files in the docs directory. Most of what these files do is simply import docstrings from the source code. But they also do things like add tables and indexes. If you've added a new class to a module, search the docs directory for that module's .rst file and add your class (in alphabetical order) to its index. If you've added a whole new module, copy-paste another module's file and add a link to your new file in the appropriate index.rst file.

Using Sphinx the documentation in docs can be converted to HTML, PDF, and other formats. In particular, we use it to generate the documentation on http://pybamm-param.readthedocs.io/

Building the documentation

To test and debug the documentation, it's best to build it locally. To do this, navigate to your pybamm-param directory in a console, and then type:

python -m tox -e docs

And then visit the webpage served at http://127.0.0.1:8000. Each time a change to the documentation source is detected, the HTML is rebuilt and the browser automatically reloaded.

Example notebooks

Major pybamm-param features are showcased in Jupyter notebooks stored in the examples directory. Which features are "major" is of course wholly subjective, so please discuss on GitHub first!

All example notebooks should be listed in examples/README.md. Please follow the (naming and writing) style of existing notebooks where possible.

All the notebooks are tested daily.

Infrastructure

Setuptools

Installation of pybamm-param and dependencies is handled via setuptools

Configuration files:

setup.py

Continuous Integration using GitHub actions

Each change pushed to the pybamm-param GitHub repository will trigger the test and benchmark suites to be run, using GitHub actions.

Tests are run for different operating systems, and for all python versions officially supported by pybamm-param. If you opened a Pull Request, feedback is directly available on the corresponding page. If all tests pass, a green tick will be displayed next to the corresponding test run. If one or more test(s) fail, a red cross will be displayed instead.

In all cases, more details can be obtained by clicking on a specific run.

Configuration files for various GitHub actions workflow can be found in .github/worklfows.

Codecov

Code coverage (how much of our code is actually seen by the (linux) unit tests) is tested using Codecov, a report is visible on https://codecov.io/gh/paramm-team/pybamm-param.

Configuration files:

tox.ini

Read the Docs

Documentation is built using https://readthedocs.org/ and published on http://pybamm-param.readthedocs.io/.

Google Colab

Editable notebooks are made available using Google Colab following this link.

GitHub

GitHub does some magic with particular filenames. In particular:

  • The first page people see when they go to our GitHub page displays the contents of README.md, which is written in the Markdown format. Some guidelines can be found here.
  • The license for using pybamm-param is stored in LICENSE, and automatically linked to by GitHub.
  • This file, CONTRIBUTING.md is recognised as the contribution guidelines and a link is automatically displayed when new issues or pull requests are created.

Acknowledgements

This CONTRIBUTING.md file, along with large sections of the code infrastructure, was copied from the excellent PyBaMM GitHub repo, which in turn was copied from the excellent Pints GitHub repo