ojdo / toolchest

A common repository for tools used in energy modeling.

Openmod's Python Toolchest

This project serves as a catch-all for openmod devs' useful python tools and APIs (though we are generally language lovers and are not limited to Python specifically).

For the foreseeable future, this repo is a bit adhoc -- anything of use that fits the general theme of energy modeling is welcome. We try to split additions by subject into the appropriate files (e.g., GIS-related work to gis.py, etc.).

The contributors to this repository strive to write clear, understandable, tested, and documented code. We recognize this requires a nontrivial effort and respect the effort of others by being willing to review pull requests and otherwise offer comments, critiques, and first-user experiences.

Communication

Apart from using the issue tracker, please join the listserv for any in depth discussions.

Dependencies

As this is a hodgepodge of tools, different tooling requires different dependencies.

General

0. numpy
1. pandas
2. scipy

GIS

0. fiona
1. rasterio
2. shapely

Modeling & Optimization

0. pyomo

Testing

0. nose

Documentation

0. Sphinx

Installing

You can install toolchest like any other python module

./setup.py install

or for local installations

./setup.py install --user

Testing

From the root directory, run

nosetests -w tests

Documentation

On *Nix Platforms

After you install the project locally, you can generate documentation by

cd docs
make html

You can serve the documentation locally via

make serve

You can then view the docs at http://localhost:8000/build/html/

On Windows

Follow the above instructions replacing make with ./make.bat.

Contributing

toolchest currently follows a master-branch based work flow. All features introduced in pull requests are merged directly into master. Should the code base become more complex, it is likely that we will transition to a develop-master git-based release work flow, as described here.

We follow semantic versioning for version numbering.

Any contribution can be pulled into master via a Pull Request provided it meets the following conditions:

0. follows pep8 style
1. is documented with docstrings formatted in the numpy style
2. is tested
3. passes CI on both Windows and Linux
4. is reviewed by at least one other contributor

Documentation Caveat

Contributions that upgrade only documentation are the sole caveat to the above requirements. Documentation-only additions can be pushed directly to the master branch. However, if a review is desired, they can of course go through the process as well.

Following Style Guides

Style guides are always annoying to follow at first but are immensely useful. Feel free to hook in autopep8 to your favorite editor to automatically fix any style issues. For emacs, you can add the following lines

; see https://github.com/paetzke/py-autopep8.el
(require 'py-autopep8)
(add-hook 'python-mode-hook 'py-autopep8-enable-on-save)

Conflicts between Contributors

Should any conflicts arise in the course of the project, without any other particularly good solution, resolution will follow a majority rule on the listserv.