Engine Module

class src.model.engine.CalculationEngine(backups_count=3)

Bases: object

Orchestrates the calculation process across multiple nodes within a calculation graph.

Manages the lifecycle of calculation nodes, their strategies, and the input/output data flow. It allows for dynamic updates to calculation strategies and input parameters, facilitating flexible and adaptable calculation processes.

Attributes:

current_parameters (InputParameters): The current set of parameters for calculations. old_parameters (InputParameters, optional): The previous set of parameters, stored for reference. nodes (dict): A dictionary of calculation nodes, keyed by their unique names. old_output_data (CalculationResults, optional): The previous set of calculation results. current_output_data (CalculationResults): The current set of calculation results being populated.

Methods:

get_or_create_node: Retrieves an existing calculation node or creates a new one if not present. add_or_update_node: Adds a new calculation node or updates an existing node’s strategy. update_parameters: Updates the calculation parameters and archives the current results. run_calculations: Executes the calculations across all nodes in the graph.

add_or_update_node(node_name: str, strategy=None)

Adds a new calculation node or updates the strategy of an existing node.

Parameters:

node_name (str): The name of the node to add or update. strategy (CalculationStrategy, optional): The calculation strategy to assign to the node.

build_dependency_tree(path=None)

Builds a nested dictionary representing the dependency tree of the calculation graph. Each key in the dictionary is a node name, and its value is a dictionary of its dependencies. Optionally saves the tree to a JSON file if a path is specified.

Parameters:

path (str, optional): The file path where to save the dependency tree in JSON format.

If not specified, the tree is not saved to a file. MUST BE A FULL PATH

Returns:

dict: A nested dictionary representing the dependency tree of the entire calculation graph.

build_inverse_dependencies()

Constructs a map of inverse dependencies for each node to efficiently update dependent nodes when parameters change. This map is used for identifying which nodes need recalculating when input parameters are updated.

check_for_cycles()

Performs a cycle detection in the graph of calculation nodes to prevent infinite recursion or deadlock This method implements a depth-first search (DFS) algorithm to traverse the graph and detect cycles.

A cycle in the graph is detected if a node is encountered that is already in the current path (stack) from the root of the DFS. If such a cycle is detected, an exception is raised to indicate the error.

Raises:

Exception: If a cyclic dependency is detected among the calculation nodes.

How it works:

1. Utilizes visited and stack sets to track nodes already explored and the path being traversed during depth-first search (DFS), respectively. 2. Employs a recursive visit function to perform DFS from any given node, identifying and visiting all its

dependencies.

3. Marks nodes as visited by adding them to visited and stack upon exploration. This helps in tracking the DFS path and detecting cycles. 4. Recursively explores all dependencies for each node. Dependencies are defined by the node’s strategy, reflecting the calculation dependencies. 5. Removes a node from stack once all its dependencies are explored (when it reaches the leaves), signifying the completion of its DFS branch. 6. Detects cycles when a node appears in stack more than once during its visit, indicating a path looped back on itself, and raises an exception. 7. Iterates over all nodes in the graph, ensuring every node is visited, which accommodates for any disconnected components within the graph.

Note:

This method should be called every times the graph is modified (nodes added or updated). Detecting cycles beforehand prevents runtime errors due to infinite recursion or deadlock situations. WARNING : DSF algorithm may take a long time to execute if the graph is very large. It should only be used when updating the graph.

clear_calculation_results()

Clears all data from the saved_data_results list at a specific index.

count_nodes()

Returns the number of nodes in the calculation graph.

Returns:

int: The number of calculation nodes in the graph.

delete_node(node_name)

Deletes a node from the calculation graph. :param node_name: :return:

export_inverse_dependencies_to_json(file_path)

Exports the current inverse dependencies map to a JSON file, useful for debugging or documentation purposes.

Parameters:

file_path (str): The file path where the JSON data should be saved.

find_max_distances_to_leaves(dependency_tree)

get_affected_nodes(changed_params: dict)

Identifies nodes affected by the changed parameters.

Parameters:

changed_params (dict): A dictionary of changed parameters.

Returns:

Set[str]: A set of node names that are affected by the changed parameters.

get_nodes_affected_by_strategy_swap(node_name)

Identifies nodes affected by a strategy swap on the specified node.

Parameters:

node_name (str): The name of the node where the strategy was swapped.

Returns:

Set[str]: A set of node names affected by the strategy swap, including the node itself and all dependent nodes.

get_or_create_node(node_name: str) → CalculationNode

Retrieves an existing node by its name or creates a new one if it doesn’t exist.

Parameters:

node_name (str): The name of the node to retrieve or create.

Returns:

CalculationNode: The retrieved or newly created calculation node.

run_calculations(node_names=None)

Executes the calculations for all nodes in the calculation graph.

Iterates over each node, performing calculations based on their strategies and the current set of parameters. Results are stored in current_output_data.

THIS METHOD shouldn’t be called directly, it should be called by update_parameters method

save_calculation_results(index)

Saves the current calculation results to a specific index in the saved_data_results list.

swap_strategy_for_node(node_name, strategy_instance, new_parameters)

update_parameters(new_parameters: InputParameters)

Updates the parameters used for calculations and archives the current results.

Parameters:

new_parameters (InputParameters): The new set of parameters for subsequent calculations.