Developer Instruction

This page contains general instructions for the developers that are working on the PyHub.

Reporting Issues

If you encounter an issue or a missing feature, you can report it on github. Please attach a detailed description and a tag (bug, enhancement,…)

Setting Up the Development Environment

To develop actively on the tool, you can follow the subsequent steps (feel free to chose a different IDE or environment management):

Make sure you have Python >=3.12 installed on your computer
Clone the repository to you drive
Create a virtual environment for this project. You can do this using PyCharm:
- Open the project in PyCharm
- Go to File -> Settings -> <project_name> -> Python Interpreter
- Select Add Local Interpreter from the Add Interpreter
- In the left-hand pane of the Add Python Interpreter dialog, select Virtualenv Environment
- Add a Base Interpreter
Install all required packages to your virtual environment by using poetry. In PyCharm

you can do this with:

Move to the terminal in PyCharm, it is located on the bottom. If the virtual environment was correctly installed, you should see a (venv) in front of the path
Execute the command pip install poetry
Execute the command poetry install to install all required packages

Now, you can run main.py after specifying the right paths. In PyCharm, you can do this:
- Click on Edit configuration, in the upper right corner of the screen
- Click Add new…
- Name your configuration as you like (e.g. Run main)
- Select Python as an interpreter and click ok
- You can run the file.
If you are planning to contribute to the main version, it is handy to also install a pre-commit hook. You can do this by running pre-commit install from the terminal.

Codebase Overview

The codebase is divided into the following parts:

Data preprocessing: defines the input data, has helper functions to change data easily
Data management: reads and processes input data before a model is constructed
Model construction: module containing functions to construct individual parts of the model.
Components: module containing all technology and network models that are available
Result management: contains functions to export the optimization results
Test: test suit

Development Workflow

The main branch contains the working and published version. The development branch contains a version being prepared for the next release. New features or bug fixes are developed on a separate branch and then merged via a pull request to the development branch. At each pull request to the development branch, the github CI checks if all tests succeed and if the code is correctly formatted. Each pull request needs at least one approved review.

Before a pull request, tests can be locally run with pytest in the terminal.

Coding conventions

Naming

To keep the code consistent and clear for other developers, try to use the coding conventions that are described below.

For the Pyomo classes we use:

Type	Code
Objective	objective…
Constraint	const…
Piecewise	const…
Set	set…
Block	b…
Var	var…
Param	para…
Disjunct	dis…
Disjunction	disjunction..
rule	init…

Other names that are regularly used in AdOpT-NET0 are:

Type	Code
Timestep	t…
Carrier	car…
Node	node…
Network	netw…
Technology	tec…
Consumption	cons…
Input	input…
Output	output…

Documentation

We require all classes and functions to have a docstring and type annotations (where possible/convenient). The following should be noted:

The doctring starts with a single line describing in brief the class/method
We use the reStructuredText format for parameters and returns
Type annotations to functions should be added for standard types (e.g. str, int, pd. DataFrame,…) but not for very specific types (e.g. ModelHub, pyo.Constraint,…). The same holds for return types
Where required, include the documentation in the sqhinx build of the documentation that is published alongside this package.

Additionally, refer to the following guides on documentation:

As such, the documentation of a function can look like this:

def set_capex_model(config: dict, economics) -> int:
    """
    Sets the capex model of a technology

    Takes either the global capex model or the model defined in respective technology
    :param dict config: dict containing model information
    :param economics: Economics class
    :return: CAPEX model
    :rtype: int
    """
    capex_model = economics.capex_model
    if capex_model != 4:
        if config["economic"]["global_simple_capex_model"]["value"]:
            capex_model = 1

    return capex_model