16 KiB

Raw Blame History

Calculator MAV - Hybrid CAS Application Logic

Overview

This document describes the operational logic of the Calculator MAV (Hybrid Computer Algebra System), focusing on the semantic flow from user input to result display. The application implements a distributed tokenization system with automatic type discovery, pure algebraic evaluation, and hybrid symbolic-numeric computation.

Architecture Components

1. Application Entry Point (calc.py)

The launcher serves as the system bootstrap, handling:

Logging Infrastructure: Establishes comprehensive error tracking with automatic log rotation
System Verification: Validates dependencies and environment setup
Error Recovery: Provides detailed error reporting with context-aware debugging information
Application Lifecycle: Manages startup, execution, and graceful shutdown

2. Main Application Interface (main_calc_app.py)

The GUI application provides:

Dual-Pane Interface: Synchronized input and output panels with smart resizing
Real-time Evaluation: Debounced input processing with automatic width adjustment
Interactive Results: Clickable elements for plots, matrices, and complex data structures
Dynamic Help System: Context-aware assistance using registered type helpers

3. Type Discovery System (type_registry.py)

The core innovation implementing:

Automatic Class Detection: Scans custom_types directory for *_type.py files
Dynamic Registration: Loads classes and their capabilities without code modification
Tokenization Pattern Collection: Aggregates parsing rules from individual types
Context Building: Creates unified namespace for evaluation engine

Computation Flow

Phase 1: Input Processing

When a user types in the input panel, the system triggers a processing cycle:

Input Capture: The text widget captures keystrokes and triggers debounced evaluation after 300ms of inactivity. Special handling occurs for dot notation (triggering autocomplete) and real-time content analysis.

Content Parsing: The entire input content is split into lines, with each line processed independently. Empty lines and comments (starting with #) are preserved but bypassed during evaluation.

Context Reset: Before each full evaluation cycle, the algebraic engine clears its internal state, ensuring consistent results regardless of previous computations.

Phase 2: Distributed Tokenization

The tokenization system operates on a priority-based pattern matching approach:

Pattern Discovery: Each registered type contributes tokenization patterns with priority levels. Higher priority patterns (more specific) are applied first, preventing conflicts between similar syntaxes.

Expression Transformation: The universal tokenizer applies transformations in priority order:

Base number patterns (16#FF, 2#1010) are converted to IntBase constructor calls
Four-element patterns (192.168.1.1, 10.x.y.z) become FourBytes instances
Specialized prefixes (0x, 0b) are handled by specific type patterns

Bracket Parser Integration: After tokenization, the bracket parser handles the simplified syntax transformation from Type[value] to Type("value") constructor calls.

Phase 3: Line Classification

The pure algebraic engine analyzes each processed line to determine its semantic type:

Assignment Detection: Lines matching "variable = expression" where the left side is a valid Python identifier are classified as assignments. These create symbol bindings and optionally add implicit equations if undefined symbols are present.

Equation Recognition: Lines containing equals signs that aren't simple assignments become equations. The system distinguishes between algebraic equations (=) and SymPy comparisons (==, <=, >=, !=).

Solve Shortcuts: The pattern "variable=?" is recognized as shorthand for solve(variable), providing quick variable resolution.

Expression Evaluation: All other lines are treated as mathematical expressions for symbolic or numeric evaluation.

Phase 4: Symbolic Evaluation

The evaluation engine operates in pure algebraic mode:

SymPy Integration: All mathematical operations prioritize symbolic representation, maintaining exact forms (fractions, radicals, symbolic expressions) whenever possible.

Dynamic Context: The evaluation context combines:

Base mathematical functions (sin, cos, integrate, solve, etc.)
Dynamically registered custom types from the type discovery system
User-defined variables from previous assignments
Automatic symbol creation for undefined variables

Hybrid Object Handling: Custom types (IP4, IntBase, FourBytes, etc.) maintain their native operations while integrating seamlessly with SymPy algebra through the SympyClassBase inheritance pattern.

Phase 5: Smart Solving

The equation system implements intelligent resolution:

System Building: Each equation is added to a persistent equation list, with variable extraction and dependency tracking.

Variable Resolution: The solve shortcut (variable=?) triggers sophisticated resolution logic:

Single-variable equations are solved directly
Multi-variable systems use SymPy's constraint solver
Underdetermined systems provide parametric solutions
Overdetermined systems report conflicts with context

Automatic Substitution: Known variable values are automatically substituted into symbolic expressions, providing immediate numeric evaluation when all symbols are resolved.

Phase 6: Result Processing

The evaluation results undergo format optimization:

Display Selection: The system determines the most informative representation:

Symbolic form is preserved for exact mathematical expressions
Numeric approximations are provided when significantly different from symbolic form
Custom type representations use their native display methods

Interactive Enhancement: Complex results (plots, matrices, large lists) are converted to interactive placeholders that open detailed views when clicked.

Error Context: Failed evaluations trigger contextual help suggestions from registered type helpers, providing guidance based on input patterns.

Phase 7: Output Synchronization

The GUI updates reflect the complete evaluation state:

Parallel Display: Input and output panels maintain line-by-line correspondence, with synchronized scrolling and visual alignment.

Color Coding: Results are tagged with semantic colors:

Symbolic expressions in blue
Numeric results in green
Equations in purple
Errors in red
Helper suggestions in gold

Layout Adaptation: The input panel automatically resizes based on content width, maintaining optimal visibility for both mathematical expressions and code.

Key Semantic Principles

Pure Algebraic Approach

Unlike traditional calculators, this system treats every assignment as a potential equation. Variables maintain their symbolic nature until explicitly evaluated, enabling sophisticated algebraic manipulation.

Distributed Extensibility

The type system allows seamless addition of new mathematical objects without modifying core engine code. Each type contributes its own tokenization patterns, helper functions, and algebraic integration.

Context Preservation

The evaluation engine maintains a persistent mathematical context across all input lines, enabling complex multi-step calculations and equation system building.

Smart Automation

The system automatically:

Creates symbols for undefined variables
Applies substitutions when variables are resolved
Provides numeric approximations when helpful
Suggests corrections for invalid input patterns

Hybrid Integration

Custom types (networking, programming, engineering) integrate seamlessly with pure mathematical operations, enabling domain-specific calculations within a unified algebraic framework.

This architecture enables the calculator to function as both a powerful symbolic mathematics tool and a specialized computational environment for technical domains, with the flexibility to expand into new areas through the distributed type system.

@startuml Calculator_MAV_Flow
!define RECTANGLE class

title Calculator MAV - Hybrid CAS Processing Flow

start

:User types in input panel;
note right: GUI captures keystrokes\nwith 300ms debounce

:Input Processing Phase;
partition "Input Capture" {
  :Split content into lines;
  :Preserve comments and empty lines;
  :Clear engine context for fresh evaluation;
}

:Distributed Tokenization Phase;
partition "Pattern Matching" {
  :Discover tokenization patterns from registered types;
  note left: Type registry auto-discovers\npatterns from custom_types/*
  :Apply high-priority patterns first;
  note right: 16#FF → IntBase("FF", 16)\n2#1010 → IntBase("1010", 2)
  :Apply medium-priority patterns;
  note right: 192.168.1.1 → FourBytes("192.168.1.1")
  :Apply bracket parser transformations;
  note right: Type[value] → Type("value")
}

:Line Classification Phase;
partition "Semantic Analysis" {
  if (Line contains "=?") then (yes)
    :Classify as Solve Shortcut;
  elseif (Simple assignment pattern?) then (yes)
    :Classify as Assignment;
    note right: variable = expression\nwhere left side is valid identifier
  elseif (Contains = but not assignment?) then (yes)
    :Classify as Equation;
    note right: x**2 + 2*x = 8\na + b == 10
  else (no)
    :Classify as Expression;
  endif
}

:Symbolic Evaluation Phase;
partition "Algebraic Processing" {
  if (Assignment type?) then (yes)
    :Create symbol binding;
    :Check for undefined symbols;
    if (Has undefined symbols?) then (yes)
      :Add implicit equation to system;
    endif
  elseif (Equation type?) then (yes)
    :Parse left and right sides;
    :Create SymPy Eq object;
    :Add to equation system;
  elseif (Solve shortcut?) then (yes)
    :Extract variable name;
    :Trigger smart solving;
  else (Expression)
    :Evaluate with SymPy priority;
    :Maintain symbolic form;
    :Auto-create undefined symbols;
  endif
}

:Smart Solving Phase;
partition "Equation Resolution" {
  if (Solve shortcut triggered?) then (yes)
    :Find equations containing variable;
    if (Single variable equations?) then (yes)
      :Solve directly;
    elseif (Multi-variable system?) then (yes)
      :Use SymPy constraint solver;
      :Handle parametric solutions;
    else (no equations)
      :Return current symbol value;
    endif
  endif
  :Apply automatic substitutions;
  note right: Substitute known values\ninto symbolic expressions
}

:Result Processing Phase;
partition "Output Formatting" {
  :Determine optimal representation;
  if (Complex result?) then (yes)
    :Create interactive placeholder;
    note right: Plots, matrices, large lists\nbecome clickable elements
  endif
  :Generate numeric approximation if helpful;
  :Apply semantic color coding;
  note right: Symbolic: blue\nNumeric: green\nEquations: purple\nErrors: red
}

:Output Synchronization Phase;
partition "GUI Updates" {
  :Update output panel with line correspondence;
  :Apply synchronized scrolling;
  :Auto-resize input panel based on content;
  :Enable interactive result clicking;
}

if (Error occurred?) then (yes)
  :Trigger contextual help from type helpers;
  note right: Dynamic help based on\ninput patterns and registered types
endif

stop

@enduml

@startuml Calculator_MAV_Flow_Corrected
!define RECTANGLE class

title Calculator MAV - Pure Algebraic Engine Processing Flow

start

:User types in input panel;
note right: GUI captures keystrokes\nwith 300ms debounce

:Input Processing Phase;
partition "Input Capture" {
  :Split content into lines;
  :Preserve comments and empty lines;
  :Clear engine context for fresh evaluation;
  note right: PureAlgebraicEngine.clear_context()
}

:Distributed Tokenization Phase;
partition "Pattern Matching" {
  :Apply dynamic tokenization patterns;
  note left: From get_registered_tokenization_patterns()
  :Transform expressions in priority order;
  note right: 16#FF → IntBase("FF", 16)\n192.168.1.1 → FourBytes("192.168.1.1")
  :Apply bracket parser processing;
}

:Line Classification Phase;
partition "Pure Algebraic Analysis" {
  if (Line ends with "=?") then (yes)
    :Classify as Solve Shortcut;
    note right: x=? becomes solve(x)
  elseif (Contains "=" and not comparison?) then (yes)
    :Classify as Equation;
    note right: ALL assignments become equations\nin pure algebraic mode
  else (no)
    :Classify as Expression;
  endif
}

:Pure Algebraic Evaluation;
partition "SymPy-First Processing" {
  if (Equation type?) then (yes)
    :Split on "=" sign;
    :Create SymPy Eq() object;
    :Add to equations list;
    :Extract and track variables;
  elseif (Solve shortcut?) then (yes)
    :Extract variable name;
    :Call _solve_variable_in_system();
  else (Expression)
    :Evaluate with sympify() first;
    :Maintain symbolic form;
    :Apply simplify if configured;
  endif
}

:Smart Variable Resolution;
partition "Equation System Solving" {
  if (Solve triggered?) then (yes)
    :Find relevant equations for variable;
    if (Multi-variable system?) then (yes)
      :Solve complete system with SymPy;
      :Extract specific variable;
    else (simple case)
      :Solve single variable directly;
    endif
    :Update symbol_table with result;
  endif
}

:Result Processing Phase;
partition "Output Formatting" {
  :Generate symbolic result;
  :Create numeric approximation if different;
  :Format as single-line output;
  note right: Concise format:\n"x = 5 ≈ 5.000000"
}

:Output Synchronization Phase;
partition "GUI Updates" {
  :Update output panel;
  :Apply color coding for result type;
  :Auto-resize input panel;
}

if (Error occurred?) then (yes)
  :Get help from registered helpers;
  :Display error with context;
endif

stop

note bottom : **Pure Algebraic Principle**\nAll assignments become equations\nSymbolic evaluation prioritized\nNumeric approximation secondary

@enduml

@startuml Calculator_MAV_Architecture_Corrected
!define RECTANGLE class

title Calculator MAV - Architecture with Pure Algebraic Engine

package "Application Layer" {
  [calc.py] as launcher
  [main_calc_app.py] as gui
}

package "Core Processing" {
  [main_evaluation_puro.py] as pure_engine
  [tl_bracket_parser.py] as parser
  [type_registry.py] as registry
  
  note top of pure_engine : **Pure Algebraic Engine**\n• All assignments → equations\n• SymPy-first evaluation\n• Persistent equation system\n• Smart variable resolution
}

package "Unused Components" #lightgray {
  [main_evaluation.py] as hybrid_engine
  note bottom of hybrid_engine : Not currently used\nin main application
}

package "Type System" {
  folder "custom_types/" {
    [intbase_type.py]
    [fourbytes_type.py] 
    [ip4_type.py]
    [... more types]
  }
}

package "Support Components" {
  [sympy_Base.py] as base
  [class_base.py] as classbase
  [tl_popup.py] as popup
  [sympy_helper.py] as helper
}

package "External Dependencies" {
  [SymPy Library] as sympy
  [Tkinter GUI] as tkinter
}

' Active connections
launcher --> gui : "Initialize"
gui --> pure_engine : "evaluate_line()"
pure_engine --> parser : "process_expression()"
parser --> registry : "get_registered_tokenization_patterns()"
pure_engine --> registry : "get_registered_base_context()"
pure_engine --> sympy : "sympify(), solve(), Eq()"

' Type system integration
registry --> intbase_type.py : "Auto-discover"
registry --> fourbytes_type.py : "Load patterns"
registry --> "... more types" : "Dynamic loading"

' Inheritance
intbase_type.py --> base
fourbytes_type.py --> classbase
base --> sympy

' Support
gui --> helper : "Contextual help"
gui --> popup : "Interactive results"

' Unused connection (grayed out)
hybrid_engine -.-> sympy : "Not used"

@enduml

16 KiB Raw Blame History