Calculation Helpers#

class efficalc.calculation_runner.CalculationRunner(calc_function: Callable, input_vals: dict[str, any] = None)#

A helper class for running calculation functions. It executes the provided calculation function and returns the calculation objects that were created during its execution. If input values are provided, they will override the default Input values.

Parameters:

  • calc_function (Callable) – The calculation function to be executed. This function should instantiate the relevant calculation objects and perform the necessary calculations. The function is executed without input parameters and returned values are ignored.

  • input_vals (dict[str, any], optional) – A dictionary of input values to override default values in the calculation function’s Input objects. Defaults to an empty dictionary if not provided.

calculate_all_items() → list#

Executes the calculation function and returns all calculation objects created during its execution (e.g. Assumption, Input, Calculation, Comparison, etc.). Ignores the calculation function return values.

Returns:

A list of all calculation objects instantiated by the calculation function.

Return type:

list

calculate_results(return_type: Literal['list']) → List[Calculation | Comparison]#
calculate_results(return_type: Literal['dict']) → Dict[str, Calculation | Comparison]

Executes the calculation function and filters the results to return only those Calculation and Comparison objects that have been marked as results (where result_check=True), either in a list or a dictionary format based on the ‘return_type’ parameter.

Parameters:

return_type – The type of the return value, “list” for a list of calculation objects, “dict” for a dictionary of calculation objects with their names as keys, defaults to “list”

Type:

return_type: “list” or “dict”, optional

Returns:

A list or a dictionary of calculation objects where result_check=True.

class efficalc.report_builder.ReportBuilder(calc_function: Callable, input_vals: dict[str, any] = None, long_calc_display: LongCalcDisplayType = LongCalcDisplayType.SCALE)#

A helper class to run calculation functions and generate reports based on the calculations.

This class provides methods to run a calculation function with optional input value overrides and generate an HTML report to view or print the calculations. Reports can be viewed immediately in a web browser, saved to a file, or returned as a string.

Parameters:

  • calc_function (Callable) – The calculation function to be executed. This function should define the calculations to be performed and instantiate calculation objects accordingly. It will be executed using the CalculationRunner.

  • input_vals (dict[str, any], optional) – A dictionary of values to override the calculation function’s default input values. Keys should be the names of the input objects in the calculation function and values should be the desired values for the input.

  • long_calc_display (LongCalcDisplayType, optional) – How long expressions should be altered to fit within the calculation report width. This can be either SCALE for scaling down the display size of the expression or LINEBREAK to break the expression into multiple lines. defaults to SCALE

get_html_as_str() → str#

Runs the calculation function with the provided input overrides and generates a string that is a complete HTML document with the calculation report.

Returns:

The HTML report as a string.

Return type:

str

save_report(save_folder: str, filename: str = 'calc_report', open_on_save: bool = False) → str#

Runs the calculation function with the provided input overrides and saves the calculation report at the specified location.

The report is generated as an HTML file with the provided file_name and saved at the provided folder_path. It will also open in the default web browser if open_on_create is set to True. If the folder_path does not exist, it will be created.

Parameters:

  • save_folder (str) – the path to the folder where the report will be saved

  • filename (str, optional) – the name of the html file that will be created in the folder_path, defaults to “calc_report”

  • open_on_save (bool) – if True, the report will be opened in the default web browser, defaults to False

Returns:

the complete filepath of the saved html file

Return type:

str

view_report() → str#

Runs the calculation function with the provided input overrides and opens up the calculation report in the default web browser. The report is generated as a temporary HTML file which can be printed to PDF or any other format.

Returns:

The path to the temporary HTML file.

Return type:

str

class efficalc.report_builder.LongCalcDisplayType(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

An enumeration for controlling how to display long mathematical expressions in reports.

Variables:

  • SCALE – Scale the expression display and font size down to fit within the report width

  • LINEBREAK – Break the expression into multiple lines to fit within the report width

efficalc.save_calculation_item(item)#

Save an item to the global store of all calculation items.

efficalc.clear_saved_objects()#

Clear all saved calculation items from the global store.

efficalc.get_override_or_default_value(input_name: str, default_value: any)#

Get the default override value for a given input name from the global store. If no override is found, returns the default value.

efficalc.set_input_default_overrides(default_overrides: dict[str, any])#

Set default override values for input names in the global store.

efficalc.get_all_calc_objects() → list#

Get all calculation objects saved in the global store.

efficalc.clear_all_input_default_overrides()#

Clear all input default overrides from the global store.