Skip to content

Latest commit

 

History

History
141 lines (106 loc) · 5.29 KB

IOperate_Documentation.md

File metadata and controls

141 lines (106 loc) · 5.29 KB

Understanding the IOperate Interface in OpNode

Overview

The IOperate interface in the OpNode project provides a powerful mechanism for attaching operations to nodes in a tree structure. This creates a dynamic calculation system where operations can be performed on child nodes and automatically recalculated when dependencies change.

Architecture

Core Interfaces

  1. IOperate Interface

    • Extends IChange for change tracking
    • Properties: Symbol (string representation), Operate(PNode node) method
    • Allows operations to be attached to nodes

  2. IChange Interface

    • Changed property: tracks if operation needs recalculation
    • Change(PNode node) method: marks operation as changed
    • ChangeFalse(PNode node) method: resets change flag

Core Classes

  1. PNode Class

    • Extends TreeNode to represent nodes in tree structure
    • Contains List<IOperate> operations to store attached operations
    • Key properties: Name, Value (for data), ErrorString (for errors)
    • Key methods:
      • AddOperation(IOperate operation): Attaches operation and executes it
      • PerformOperations(): Executes all operations on the node
      • HasChangedOperations(): Checks if any operations need recalculation
      • OperationChanged(): Marks parent operations as needing recalculation

  2. Operator Abstract Class

    • Base implementation of IOperate
    • Handles change tracking and propagation
    • Implements the Change() method to notify parent nodes

  3. Sum Class (Example Implementation)

    • Concrete implementation of Operator
    • Performs summation of all child node values
    • Stores result in parent node's Value property
    • Includes error handling for overflow and parsing failures

How It Works

Basic Operation Flow

  1. Node Creation: Create nodes with names and optional values
  2. Tree Building: Add child nodes to parent nodes using AddChild()
  3. Operation Assignment: Add operations to nodes using AddOperation()
  4. Automatic Calculation: Operations immediately execute when added
  5. Change Propagation: When child values change, parent operations are marked for recalculation
  6. Lazy Recalculation: Operations only recalculate when HasChangedOperations() returns true

Example Workflow

// Create a sum node
var sumNode = new PNode("sum", "");

// Add child nodes with values
var item1 = new PNode("item1", "25");
var item2 = new PNode("item2", "75");
sumNode.AddChild(item1);
sumNode.AddChild(item2);

// Add Sum operation - automatically calculates 25 + 75 = 100
sumNode.AddOperation(new Sum());
// sumNode.Value now contains "100"

// Change a child value
item1.Value = "50";
item1.OperationChanged(); // Notify parent that recalculation needed

// Recalculate
sumNode.PerformOperations(); // Now calculates 50 + 75 = 125

Key Features

1. Lazy Evaluation

  • Operations only recalculate when HasChangedOperations() returns true
  • Optimizes performance by avoiding unnecessary calculations
  • Change tracking propagates up the tree hierarchy

2. Error Handling

  • Operations can report errors via the ErrorString property
  • Sum operation handles overflow and parsing errors gracefully
  • Failed operations don't crash the system

3. Nested Operations

  • Operations can be applied to nodes that themselves have operations
  • Creates a hierarchical calculation system
  • Child operations execute before parent operations

4. Extensibility

  • New operations can be created by implementing IOperate
  • Operations can have symbols/icons for UI representation
  • Plugin-like architecture allows easy addition of new functionality

Available Operations (from original codebase)

  • Sum: Adds all child node values
  • Multiply: Multiplies all child node values
  • Divide: Divides child node values
  • Subtract: Subtracts child node values
  • Sin, Cos, Tan: Trigonometric operations
  • Min, Max, Average: Statistical operations

Business Value

The IOperate interface provides a foundation for building calculation engines that could be used in:

  1. Financial Modeling: Create spreadsheet-like calculation trees
  2. Engineering Calculations: Build complex formula dependencies
  3. Data Processing: Create ETL-like transformation pipelines
  4. Game Development: Build skill trees or stat calculation systems
  5. Business Rules: Implement complex business logic with dependencies

Demonstration Results

The working demonstration shows:

  • ✅ Basic sum operation functionality
  • ✅ Child node addition and value changes
  • ✅ Automatic recalculation when dependencies change
  • ✅ Tree structure visualization
  • ✅ Change propagation system
  • ✅ Error handling for invalid values
  • ✅ Nested operation support (with some limitations)

Potential Improvements

  1. Better Change Tracking: More granular change detection
  2. Circular Dependency Detection: Prevent infinite calculation loops
  3. Expression Parsing: Allow formula-based operations
  4. Validation Framework: Type checking and constraint validation
  5. Persistence: Save/load operation trees from storage
  6. Performance Optimization: Parallel calculation for independent branches

This architecture demonstrates a well-designed plugin system that could be extended to support a wide variety of calculation and transformation operations.