Usage
=====

.. _installation:

Installation
------------

An important prerequisite is to have [GAMS](https://www.gams.com/) installed on your system, as this packages calls certain GAMS commands through python.
To use BackboneTools, install it using pip:

.. code-block:: console

   (.venv) $ pip install backbonetools

Examples of usage
------------

Very easy example
~~~~~~~

.. code-block:: python

   from backbonetools.io import BackboneResult 

   result = BackboneResult('someBackboneOutputFile.gdx')

   # any symbol is available as DataFrame
   gen_df = result.r_gen_gnuft()
   gen_df.head()

This yields something like this:

+----+-------+--------+---------------+-----+----+--------+
|    | grid  | node   | unit          | f   | t  | Val    |
+====+=======+========+===============+=====+====+========+
|  0 | elec  | AT0 0  | AT0 0 CCGT    | f00 | 6  | 3295.9 |
+----+-------+--------+---------------+-----+----+--------+
|  1 | elec  | AT0 0  | AT0 0 CCGT    | f00 | 7  | 3295.9 |
+----+-------+--------+---------------+-----+----+--------+
|  2 | elec  | AT0 0  | AT0 0 CCGT    | f00 | 8  | 3295.9 |
+----+-------+--------+---------------+-----+----+--------+
|  3 | elec  | AT0 0  | AT0 0 CCGT    | f00 | 9  | 3295.9 |
+----+-------+--------+---------------+-----+----+--------+
|  4 | elec  | AT0 0  | AT0 0 CCGT    | f00 | 10 | 3295.9 |
+----+-------+--------+---------------+-----+----+--------+

More detailed explanations of the existing functionalities can be found in the :ref:`API` description.

Calculate full load hours
~~~~~~~

backbonetools can easily be used to calculate full load hours of units:

.. code-block:: python

   import backbonetools
   
   bb_input = backbonetools.io.inputs.BackboneInput("path_to_input.gdx")
   bb_result = backbonetools.io.BackboneResult("path_to_result.gdx")

   # get generated energy from result
   generation = bb_result.r_gen_gnu().set_index("unit")[["Val"]]
   # get invested capacity from result
   invested_cap = bb_result.r_invest_unitCount_u().set_index("unit")

   # read previously installed capacity from input
   p_gnu_io = bb_input.p_gnu_io()
   p_gnu_io = p_gnu_io.loc[p_gnu_io["Dim1"] == "elec"]
   p_gnu_io = p_gnu_io.loc[p_gnu_io["Dim5"] == "capacity"]
   p_gnu_io.set_index("Dim3", inplace=True)
   p_gnu_io = p_gnu_io[["Val"]].dropna()

   # calculate full load hours
   unitname = "PT1 0 solar"
   flh = generation.loc[unitname]/(p_gnu_io.loc[unitname] + invested_cap.loc[unitname])