Contributing

Note

See also Contact the developers for information on the mailing list.

Brightway2 is designed to be easy to use and develop for. The modular structure of Brightway2 means that you don’t have to learn everything at once - pick the subject that best suits your interests and skills, download the code, and start hacking!

Code of conduct

Brightway follows the Contributor Covenant; more details are found in the file CODE_OF_CONDUCT.md in each repository.

Required packages

In addition to the Brightway2 modules you want to work on, you should also install the following:

  • nose: A library for finding and running tests.
  • sphinx: A library for writing and formatting documentation.
  • mercurial: A distributed version control system.

This can be done easily. Try to install these packages through Canopy or anaconda, if you are using them. Otherwise, use pip:

pip install nose sphinx mercurial

Using mercurial

Mercurial is a distributed version control system, which records changes made in your source code over time, and allows changes from multiple people to merged to a single code base. hginit is a good guide to get started with Mercurial.

Contributing changes to Brightway2

The preferred way to submit changes is with a pull request on Bitbucket. A pull request is a fancy way of saying “Hey! I made some changes to what you already had in my own playground over here - how about you merge my changes back into the main source code repository.” The instructions on pull requests are slightly different for Windows users and OS X/Linux users. For small changes, and especially things like typos, you can even use the online text editor without having to download anything.

No Python needed - making graphics better

One easy way of helping out that doesn’t require any knowledge of Python, matrices, or even actually life cycle assessment at all, is to help make the existing graphics better or introduce new ones. Each graphic in the LCA report is also available in a online:

The code here is editable, and the changes you make will be immediately reflected in the display. Feel free to make some tweaks, or even major changes, to make the visualizations nicer, easier to understand, and simpler. If you have for other graphics that would be useful in interpreting LCA results, or in exploring inventory datasets or impact assessment methods, feel free to Contact the developers to get a sample dataset.

Principles for good code

  • Follow the Zen of Python - if you don’t know what this is, try typing import this in a python shell.
  • Follow style guides like PEP 8. Tools like pylint can help.
  • Write tests, and check test coverage.
  • Use sphinx to write documentation while you are writing code.

Easy problems

Tune the force-directed graph parameters to avoid the “hairball” problem

There are a number of parameters in the Force-directed graph, such as link distance and circle radius, which can be tuned to make the graph easier to understand. Go ahead and try to change them a bit and see what happens!

Implement other graphs from D3.js

Here are some possibilities we could include in either LCA reports, or in exploring or analyzing inventory databases:

Improve report layout and CSS

Those who know a bit about design, or at least think that they do, are welcome to make the report page better. Here is an example report page.

Improve test coverage

Each of the three calculation packages has an online report available. Many of the test coverage failures can be easily resolved with simple tests, and writing simple tests is a great way to get started with Python and Brightway2.

Medium problems

Find holes in tests

Tests always have edge cases that weren’t anticipated by the developers, and coverage doesn’t test for exceptions. Finding these edge cases or exceptions is a thankless but extremely important part of making robust software.

Package and test the Intel MKL version of Scipy

The Intel MKL library could provide significant speed benefits, but this needs to be tested. The Intel MKL version of Scipy is packaged with Anaconda, so testing its speed versus the current native BLAS should be relatively easy.

See also:

Ecospold exporter

The base Brightway2 data format doesn’t include fields for all of the Ecospold data format, but we can still export that data that is available in the Ecospold format. This would help in making Brightway2 data more transportable. It is not necessarily a difficult task, but writing a lot of XML processing code is never very much fun.

Improve the activity-browser

The existing activity-browser has a lot of potential, but still needs a lot of work.

Hard problems

Sankey flow diagram

Sankey diagrams are helpful for showing the flows of raw material inputs or environmental impact through the supply chain. There are some initial ideas, see also a simpler example on how to do this in D3, but the problem here is actually twofold:

  1. Disaggregating the supply chain graph in a reasonable fashion without having it either collapse or retain too many deep links
  2. Graph layout and display of additional information in D3

Playing well with others

Because the data model of Brightway2 is relatively simple, there is a lot of potential for providing data, especially numerical data and matrices, in the formats needed by other programming languages. Here are some examples: