Document meaning of "graph" and "dto"

[patnr]

Having perused eCalc for a little while, I have some questions I think might be helpful for other users as well that maybe should be documented, or at least discussed.

• What is the purpose of everything relating to "graph" in eCalc?
  Example: model = EnergyCalculator(graph=yaml_model.graph).
  Is it for generating the nice component chart that is at the top of each example in the documentation?
• Is it somehow related to DTO, and what is DTO ?
• Why was it chosen over builtin data structures (nested dicts reflecting the input yaml file) ?
• Is there an easier way to reference components than getting the id_hash from yaml_model.graph.components in order to look up something in the output of model.evaluate_energy_usage?

[TeeeJay]

Hi Patrick,

thank you very much for your interest and effort into learning how to use eCalc.

I would very much like to answer your questions, and I would do that briefly, but I will leave out a thorough explanation because the work is WIP, as it states in the readme:

eCalc™ is a work in progress (WIP) and is by no means considered a finished and final product. We currently recommend to use the YAML API when using eCalc, and only fallback to the Python API when it is strictly needed, as a breaking v2 version of the Python API is in development and expected finished in 2023.

These things WILL be changed, and we therefore do not encourage you to use this "internal structure" yet, until we have a structure that we do not intend to change in the future.

However, FWIW, I will answer your questions briefly:

What is the purpose of everything relating to "graph" in eCalc? Example: model = EnergyCalculator(graph=yaml_model.graph).
Is it for generating the nice component chart that is at the top of each example in the documentation?

This is a code internal implementation detail on how the equipment is connected together. This may change in the future. We will provide better options to get the relevant data when we are ready. For now, please use the resulting JSON or CSV files.

Is it somehow related to DTO, and what is DTO ?

This is also WIP. A DTO is a Data Transfer Object (data object that can be serialized and is possibly customized for a particular usage/serialization), but this is a bit misleading/wrongly used in the current implementation. Expect to work on
richer domain objects in the future, when using the library.

Why was it chosen over builtin data structures (nested dicts reflecting the input yaml file) ?

The current input YAML is a legacy input interface, and do not reflect a good and consistent way for the eCalc model in our opinion. Due to backwards compatibility reasons etc, the YAML file is currently what it is. We would want to go for a better structure.
Also, we want more control over the data than a nested dict would give us wrt. parsing and validation. Using Pydantic for that, gives us validation, a better description of the data and more in control of transforming the input
data structure to (any) internal data structure. We are therefore able to change the external interface (YAML) without changing the internal domain model (and vice versa).

Is there an easier way to reference components than getting the id_hash from yaml_model.graph.components in order to look up something in the output of model.evaluate_energy_usage?

Currently, no, when using the Library API.

eCalc Dev Team

[patnr]

Thank you for the response.

I have followed the setup in ecalc/examples/simple_yaml_model.ipynb (as opposed to simple_python_model) which makes use of model.yaml and therefore thought that I was following the WIP warning & recommendation no to use Python API. So my questions are mainly come from an effort to understand the computations and break down the output of eCalc. Despite the complication of cross-referencing yaml_model.graph.components with model.evaluate_energy_usage it still seems simpler (for any other purpose than print-all) than re-parsing the headers of the output csv and cross-referencing them with the input yaml.