TESPy has been developed mainly by Francesco Witte at the University of Applied Sciences Flensburg. We hope that many people can make use of this project and that it will be a community driven project in the future, as users might demand special components or flexible implementations of characteristics, custom equations, basically what ever you can think of.
We want to invite you to join the developing process and share your ideas. Your solutions may help other users as well. Contributing to the development of TESPy may help other people and it improves the quality of your code as it will be reviewed by other developers.
The easiest way of joining the developing process is by improving the documentation. If you spot mistakes or think, the documentation could be more precise or clear in some sections, feel free to fix it and create a pull request on the github repository.
Another simple first step is to program your own custom subsystems and share them in the community. For a good start just look into our tutorial How do I create custom subsystems.
A third, highly appreciated way for you to contribute is the provision of new and/or improved equations, maybe even whole characteristics for single components, such as compressor maps, characteristics for turbine efficiency or heat transfer coefficients etc..
You will find the most important information concerning the development process in the following sections. If you have any further questions feel free to contact us, we are looking forward to hearing from you!
It is recommenden to use virtual environments for the development process. Fork the repository and clone your forked tespy github repository and install development requirements with pip.
git clone https://github.com/YOUR_GITHUB_USERNAME/tespy.git cd tespy pip install -e .[dev]
In order to stay in sync with the oemof/tespy base repository, add the link to the oemof/tespy repository as remote to your local copy of tespy. We will call the link “upstream”. Fetch branches available and after that, you can pull changes from a specific branch of the oemof/tespy repository (branch “dev” in the example below).
git remote add upstream https://github.com/oemof/tespy.git git fetch upstream git pull upstream dev --rebase
--rebase comand to avoid merge commits fo every upstream pull.
If you want to make changes to tespy, checkout a new branch from your local dev
branch. Make your changes, commit them and create a PR on the oemof/tespy dev
There are different ways you can contribute
Contribute to the documentation¶
If you come across typos or grammatical mistakes or want to improve comprehensibility of the documentation, make your adjustments or suggestions and create a pull request for the dev branch. We appreciate your contribution!
Improve or add new equations¶
The components equations represent the behavior of each component. Are we missing any equations? Or do you see possibilities to improve the formulation? Add them to your code and create a pull request on the dev branch.
Add component characteristics¶
The component characteristics represent large added value for your calculation. If you have detailed information on components offdesign behavior - even for specific cases - it will improve the results. Every user can benefit from this knowlegde and thus we are very happy to discuss about the implementation of new characteristics.
To collaborate use the pull request functionality of github as described here: https://guides.github.com/activities/hello-world/
How to create a pull request¶
Fork the oemof repository to your own github account.
Change, add or remove code.
Commit your changes.
Create a pull request and describe what you will do and why. Please use the pull request template we offer. It will be shown to you when you click on “New pull request”.
Wait for approval.
Generally the following steps are required when changing, adding or removing code¶
The tests in TESPy are split up in two different parts:
doc-tests (also used as examples for classes and methods/functions)
software tests (defined in the tests folder).
The tests contain code examples that expect a certain outcome. If the outcome
is as expected a test will pass, if the outcome is different, the test will
fail. You can run the tests locally by navigating into your local github clone.
check tests PEP guidelines, the command
tests building the documentation, and the command
py3X runs the
software tests in the selected Python version.
python -m tox -e docs python -m tox -e check python -m tox -e py36 python -m tox -e py37 python -m tox -e py38
If you want to have a look at the documentation build on your local machine use the following command from the local tespy clone:
python -m sphinx docs/ path/to/html_output
Additionally, all tests will run automatically when you push changes to a branch that has a pull request opened.
If you have further questions regarding the tests, we are looking forward to your inquiry.
A good way for communication with the developer group are issues. If you find a bug, want to contribute an enhancement or have a question on a specific problem in development you want to discuss, please create an issue:
describing your point accurately
using the list of category tags
addressing other developers
If you want to address other developers you can use @name-of-developer, or use e.g. @tespy to address a team. Here you can find an overview over existing teams on different subjects and their members.
Look at the existing issues to get an idea on the usage of issues.
We mostly follow standard guidelines instead of developing own rules. So if anything is not defined in this section, search for a PEP rule and follow it.
We decided to use the style of the numpydoc docstrings. See the following link for an example.
Code comments are block and inline comments in the source code. They can help to understand he code and should be utilized “as much as necessary, as little as possible”. When writing comments follow the PEP 0008 style guide.
PEP8 (Python Style Guide)¶
We use plural in the code for modules if there is possibly more than one child class (e.g.
import heat_exchangersAND NOT
import heat_exchanger). If there are arrays in the code that contain multiple elements they have to be named in plural.
Please, follow the naming conventions of pylint
Use talking names
Variables/Objects: Name it after the data they describe (power_line, wind_speed)
Functions/Method: Name it after what they do: use verbs (get_wind_speed, set_parameter)
So far we adhere mostly to the git branching model by Vincent Driessen.
instead of the name
origin/developwe call the branch
feature branches are named like
release branches are named like
Use this nice little commit tutorial to learn how to write a nice commit message.
The general implementation-independent documentation such as installation guide, flow charts, and mathematical models is done via ReStructuredText (rst). The files can be found in the folder docs. For further information on restructured text see: https://docutils.sourceforge.io/rst.html.