Contributing to MVS

Proposed workflow

The workflow is described in the CONTRIBUTING.md file in the repository.

Unit tests (pytests)

When developing code for the MVS please make sure that you always also develop test in tests. We integrate those unit tests with pytest. Make sure that your tests are as lightweight as possible - this means that you do not always have to run the whole code to test for one feature, but can test a function with a standalone tests. Please refer to the other tests that have already been introduced.

Always aim for the test coverage button on the main page of the github repository to reach 100%!

When you do have to run the MVS itself for a test, eg. for benchmark tests, please always use the arguments -f -log warning to make the test results better readable.

Build documentation

You can build the documentation locally moving inside the docs/ folder and typing

html build

into a console, then go to docs/_build/ and open index.html into your favorite browser.

All functions in the code will be automatically documented via their docstrings. Please make sure they follow the Numpy format.

Here is how to set that in pycharm

pycharm docstring's format setting

Format of Docstrings

Please add docstrings for every function you add. As docstrings are a powerful means of documentation we give an example here:

Download: Example docstring

import pandas as pd


def example_function(arg1, argN):
    r"""
    One line no more that 80 character explaining very shortly what the function does

    More detailed explanation about the function,
    can have several lines

    Parameters
    ----------
    arg1 : str or list(str)
        description of arg1
        Default: <default value here>.

    ...

    argN : str or list(str)
        description of argN
        Default: <default value here>.

    Returns
    -------
    :class:`pandas.DataFrame<frame>`
        here comes the description
    (In case of no return, you can write what the function changes, e.g. updates
    `variable_x` with `y`.)

    Notes
    -----
    You can cite the references below using [1]_ or [2]_  add maths equations like this:

    .. math:: P=\frac{1}{8}\cdot\rho_{hub}\cdot d_{rotor}^{2}
        \cdot\pi\cdot v_{wind}^{3}\cdot cp\left(v_{wind}\right)

    with:
        P: power [W], :math:`\rho`: density [kg/m³], d: diameter [m],
        v: wind speed [m/s], cp: power coefficient

    You can also indicate here which tests are covering this function:
    This function is tested with:
    - tests.test_example_function()

    References
    ----------
    .. [1] paper 1
    .. [2] paper 2

    Examples
    --------
    # Here you can write some basic python code that is tested with pytest
    >>> import src.C2_economic_functions as e_funcs
    >>> CAPEX = e_funcs.capex_from_investment(
    ...    investment_t0=220000, lifetime=20, project_life=20,
    ...    discount_factor=0.1, tax=0.15)
    >>> round(CAPEX, 7)
    253000.0

    """
    return pd.DataFrame(...)