pycallgraphix 1.0.2
pycallgraphix is an extension of standard call graph python packages that enables users to independently select the functions they wish to include in visualizations by simply applying a function wrapper.
License: MIT License
Requires Python: >=3.7
Keywords: call graph,wrapper,visual,pycall,graphix

[![badge](https://img.shields.io/badge/launch-binder-579aca.svg?logo=data:image/png;base64,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)](https://mybinder.org/v2/gh/FZJ-IEK3-VSA/voila-tsam/HEAD?urlpath=voila/render/Time-Series-Aggregation-Module.ipynb)

<a href="https://www.fz-juelich.de/en/iek/iek-3"><img src="https://www.fz-juelich.de/static/media/Logo.2ceb35fc.svg" alt="Forschungszentrum Juelich Logo" width="230px"></a>

# pycallgraphix
pycallgraphix is a simple python package that enables users to easily visualize their python code structure. pycallgraphix takes standard [call graph](http://en.wikipedia.org/wiki/Call_graph) python packages a step further by allowing users to create a visual from only the functions they select. Users simply wrap the functions they wish to include with a pre-defined wrapper and pycallgraphix generates an image based on their connections.

## Features
* Call graph visualization of selected python functions in a PNG format
* Includes the time spent running selected functions and the number of calls to selected functions
* Color coded call graph image, based on the time spent running function calls
* Optional profiling of selected functions using cProfile

## Installation
Directly install via pip as follows:

	pip install pycallgraphix

Alternatively, clone a local copy of the repository to your computer:

	git clone https://github.com/FZJ-IEK3-VSA/pycallgraphix

Then install pycallgraphix via pip as follows:

	cd pycallgraphix
	pip install .

Finally, run the unit tests to ensure it is installed correctly:

    python -m unittest test.test_store_calls
    python -m unittest test.test_store_funcs


## Basic Workflow

A small example how to use pycallgraphix is as follows:
```python
import cProfile
from pycallgraphix.wrapper import MethodChart, register_method
```

Enable the profiler (optional):
```python
profiler = cProfile.Profile()
profiler.enable()
```

Define the call graph object. The execute function contains all the scripts or functions you wish to include in the graph. Scripts and functions do not need to be a part of the PyCallGraphObject class but all functions included in the call graph must be wrapped with the **@register_method** wrapper:
```python
class PyCallGraphObject:

    def __init__(self) -> None:
        self.execute()
        methodchart = MethodChart()
        methodchart.make_graphviz_chart(
            time_resolution=3, filename="Method_Pattern.png"
        )
        profiler.disable()
        profiler.dump_stats("profile.prof")

    def execute(self):
        self.sum_recursive(3, 4)

    @register_method
    def sum_recursive(self, a, b):
        if b > 0:
            a += 1
            b -= 1
            self.print_value(prefix='current', value=a)
            return self.sum_recursive(a, b)
        else:
            self.print_value(prefix='final', value=a)
            return a

    @register_method
    def print_value(self, prefix, value):
        print("{} value = {}".format(prefix,value))
```

Finally run the code by initializing the PyCallGraphObject:
```python
run = PyCallGraphObject()
```

If created succesfully, the resulting graph looks like:

![](https://github.com/FZJ-IEK3-VSA/pycallgraphix/blob/main/example/Method_Pattern.png?raw=true)

### Including functions from other directories and scripts

To include functions from other python files and scripts, simply import the wrapper into your script as follows:
```python
from pycallgraphix.wrapper import register_method
```

And wrap the desired functions. pycallgraphix will automatically locate it when creating the call graph:
```python
@register_method
def myExampleFunction(a, b):
    ....
```

## Detailed Example

A detailed example of what can be created with pycallgraphix was generated for one module of the House Infrastructure Simulator [(HiSim)](https://github.com/FZJ-IEK3-VSA/HiSim).

![](https://github.com/FZJ-IEK3-VSA/pycallgraphix/blob/main/example/HISIM_Method_Pattern.png?raw=true)


## License

MIT License

Copyright (c) 2022-2023 Katharina Rieck (FZJ/IEK-3), Matthew Keller (FZJ/IEK-3), Noah Pflugradt (FZJ/IEK-3), Jann Weinand (FZJ/IEK-3), Detlef Stolten (FZJ/IEK-3)

You should have received a copy of the MIT License along with this program.
If not, see https://opensource.org/licenses/MIT


## About Us

We are the [Institute of Energy and Climate Research - Techno-economic Systems Analysis (IEK-3)](https://www.fz-juelich.de/en/iek/iek-3) belonging to the [Forschungszentrum Jülich](https://www.fz-juelich.de/en). Our interdisciplinary department's research is focusing on energy-related process and systems analyses. Data searches and system simulations are used to determine energy and mass balances, as well as to evaluate performance, emissions and costs of energy systems. The results are used for performing comparative assessment studies between the various systems. Our current priorities include the development of energy strategies, in accordance with the German Federal Government’s greenhouse gas reduction targets, by designing new infrastructures for sustainable and secure energy supply chains and by conducting cost analysis studies for integrating new technologies into future energy market frameworks.


## Acknowledgments

* To create the singleton pattern, the following work was referenced:
    https://refactoring.guru/design-patterns/singleton/python/example#example-1

* pycallgraphix makes use of the [python graphviz](https://pypi.org/project/graphviz/) package.