sciencetoolnote

a tool of windows for science{simple}

Comment

sciencetoolnote

a tool of windows for science{simple}

Scientific Notebook Calculator: Ultimate Edition

A Comprehensive Technical Documentation & Architectural Analysis

📑 Table of Contents

  1. Executive Summary
  2. System Architecture & Design Philosophy
  3. Compilation & Build Environment
  4. Core Component Analysis
  5. Functional Module Breakdown
  6. User Interface Mechanics
  7. Execution Flow & Event Loop
  8. Performance Optimization Strategies
  9. Extensibility & Future Roadmap
  10. Conclusion

1. Executive Summary

The Scientific Notebook Calculator – Ultimate Edition is a sophisticated, dual-mode computational engine written in pure C. It serves as both a powerful scientific calculator and an educational reference tool, featuring a database of over 2000+ mathematical, physical, and engineering formulas. Unlike standard calculators that only perform arithmetic, this application provides semantic context: every formula is accompanied by a human-readable description, variable definitions, and categorical organization.

The application bridges the gap between symbolic computation and numerical evaluation. It features a custom-built Recursive Descent Parser capable of handling complex expressions, built-in functions, and user-defined variables. It operates in three distinct modes:

  1. GUI Mode: A Windows-native interface with dynamic input fields, real-time descriptions, and a categorized context menu.
  2. Interactive Console Mode: A REPL (Read-Eval-Print Loop) environment for quick calculations and formula discovery.
  3. CLI Batch Mode: Direct execution from the command line for scripting and automation.

By combining a robust parsing engine with an extensive library of scientific knowledge, this tool is invaluable for students, engineers, physicists, and developers who require rapid access to verified mathematical models.

2. System Architecture & Design Philosophy

2.1 Hybrid Console/GUI Architecture

The application is designed as a Hybrid Windows Application. It detects its execution context at startup:

  • If command-line arguments are present, it routes to console_main() for text-based processing.
  • If no arguments are present, it initializes the Win32 GUI subsystem via WinMain().

This design ensures maximum versatility. The core logic (parser, evaluator, formula database) is completely decoupled from the presentation layer, allowing the same computational engine to drive both the graphical interface and the terminal output.

2.2 The Recursive Descent Parser Engine

At the heart of the application lies a custom Recursive Descent Parser. This top-down parser constructs a parse tree implicitly through function calls, respecting standard mathematical order of operations (PEMDAS/BODMAS).

The parser implements four levels of precedence:

  1. Expression (expr): Handles addition (+) and subtraction (-).
  2. Term (term): Handles multiplication (*) and division (/).
  3. Power (power): Handles exponentiation (^), which is right-associative.
  4. Factor (factor): Handles numbers, variables, unary operators (-, +), parenthesized groups, and function calls.

This structure allows for the accurate evaluation of complex nested expressions like sin(x)^2 + cos(y)^2 or sqrt(a^2 + b^2).

2.3 Tokenization & Lexical Analysis

Before parsing, the input string undergoes Lexical Analysis via the tokenize() function. This phase converts the raw character stream into a sequence of Token structures.

  • Number Recognition: Uses strtod() to parse floating-point literals, including scientific notation.
  • Identifier Parsing: Distinguishes between Variables (e.g., x, mass) and Built-in Functions (e.g., sin, log) by looking up identifiers in the functions[] registry.
  • Operator Handling: Recognizes standard arithmetic operators (+, -, *, /, ^) and delimiters ((, ), ,).

2.4 Variable Substitution & Constant Resolution

The parser does not evaluate variables directly. Instead, the substitute_vars() function pre-processes the token stream.

  • Physical Constants: Special identifiers like pi, e, phi, c_light, and h_planck are resolved to their double-precision values before parsing begins.
  • User Variables: Values entered by the user in the GUI or CLI are stored in a VarEntry table. The substitutor replaces TK_VAR tokens with TK_NUM tokens containing the user's input.
  • Error Handling: If an undefined variable is encountered, the system throws a descriptive error, preventing silent failures.

3. Compilation & Build Environment

3.1 Compiler Requirements

The project is designed for GCC (MinGW) on Windows, leveraging C99 standards.

Build Command:

gcc -O2 -o sci_calc.exe main.c -lgdi32 -lcomctl32 -lm
  • -O2: Enables optimization level 2 for faster execution of the parser and math functions.
  • -o sci_calc.exe: Specifies the output executable.
  • -lgdi32: Links the Graphics Device Interface library for GUI rendering.
  • -lcomctl32: Links the Common Controls library (required for modern ComboBoxes and Buttons).
  • -lm: Links the standard Math library (libm), providing sin, cos, exp, log, etc.

3.2 Linker Dependencies

The application relies on standard Windows system libraries:

  1. user32.lib: For window management, message loops, and control creation (implicit in GCC).
  2. gdi32.lib: For drawing text and handling device contexts.
  3. comctl32.lib: For advanced UI controls like the dropdown ComboBox.
  4. msvcrt.lib: For standard C library functions (printf, malloc, strtod).

3.3 Unicode & Character Encoding

The application is built with Unicode Support (#define UNICODE and #define _UNICODE).

  • Wide Character API: Uses CreateWindowW, MessageBoxW, and WNDCLASSEXW to ensure proper rendering of international characters and symbols.
  • UTF-8 Conversion: The console mode and internal formula database use UTF-8 for string storage. Helper functions MultiByteToWideChar and WideCharToMultiByte are used extensively to bridge the gap between the UTF-8 formula database and the UTF-16LE Windows API.

4. Core Component Analysis

4.1 The Token Structure & Enumeration

The lexer produces an array of Token structs:

typedef enum {
    TK_NUM,   // Floating point number
    TK_VAR,   // Variable name (e.g., 'x', 'mass')
    TK_FUNC,  // Built-in function (e.g., 'sin', 'log')
    TK_OP,    // Operator (+, -, *, /, ^)
    TK_LP,    // Left Parenthesis
    TK_RP,    // Right Parenthesis
    TK_COMMA, // Argument separator
    TK_END    // End of expression
} TokType;

typedef struct {
    TokType type;
    double num;           // Value if TK_NUM
    char name[16];        // Name if TK_VAR or TK_FUNC
    int func_arity;       // Number of arguments expected
    double (*func)(int, double*); // Function pointer
} Token;

This structure allows the parser to handle different data types uniformly. The func pointer enables direct execution of C math library functions during the evaluation phase.

4.2 The BuiltinFunc Registry

The application supports over 30 built-in mathematical functions, registered in the functions[] array:

  • Trigonometric: sin, cos, tan, asin, acos, atan, atan2.
  • Hyperbolic: sinh, cosh, tanh.
  • Exponential/Logarithmic: exp, log (ln), log10, log2.
  • Power/Root: sqrt, cbrt, pow.
  • Special Functions: tgamma (Gamma), lgamma (Log-Gamma), erf (Error Function), j0/y0 (Bessel Functions).
  • Utility: fabs, floor, ceil, round, sign, hypot, fmod.

Each entry maps a string name to a C function pointer and defines its arity (number of arguments), enabling strict validation during parsing.

4.3 The Formula Database Schema

The core intellectual property of the application is the formulas[] array, a static database of structured knowledge:

typedef struct {
    const char *name;        // Unique identifier (e.g., "kinetic_energy")
    const char *expression;  // Parseable string (e.g., "0.5*m*v^2")
    const char *var_list;    // Comma-separated variables (e.g., "m,v")
    int nvars;               // Count of variables
    const char *category;    // Grouping (e.g., "Mechanics")
    const char *desc;        // Human-readable explanation
} Formula;

This schema allows the GUI to dynamically generate input fields based on var_list and display helpful context via desc. The expression field is stored as a string, which is parsed and evaluated on-demand, allowing for flexible reuse of the parser engine.

4.4 The Evaluation Pipeline

The calculation process follows a strict pipeline:

  1. Input: User selects a formula and enters variable values.
  2. Substitution: substitute_vars() replaces variable names in the token stream with their numeric values.
  3. Parsing: expr() initiates the recursive descent, breaking the token stream down into operands and operators.
  4. Execution: As the recursion unwinds, mathematical operations are performed. Function calls trigger the associated C function pointers.
  5. Output: The final double result is formatted and displayed.

5. Functional Module Breakdown

The formula database is categorized into 15+ distinct scientific domains.

5.1 Mathematical Domains Covered

  • Basic Arithmetic: Addition, subtraction, multiplication, division, modulus, absolute value, signum.
  • Algebra: Quadratic formula (roots, vertex, discriminant), arithmetic/geometric series, compound interest, binomial coefficients, polynomial evaluation.
  • Trigonometry: Standard identities, double-angle/half-angle formulas, Law of Sines/Cosines, Haversine formula for great-circle distance.
  • Calculus: Derivatives of common functions (power, sin, cos, exp, ln), indefinite integrals, Trapezoidal rule, Simpson's 1/3 rule, Maclaurin series expansions, Newton's Method iteration.
  • Linear Algebra: Dot products, vector magnitude, 2x2 matrix determinant, trace, eigenvalues.
  • Statistics & Probability: Variance, Z-score, Binomial/Poisson/Normal/Exponential PDFs, Confidence Intervals, Shannon Entropy.

5.2 Physics & Engineering Modules

  • Classical Mechanics: Kinematics (velocity, acceleration, displacement), Newton's Laws, Work, Energy (Kinetic, Potential, Elastic), Power, Momentum, Impulse, Torque, Centripetal Force, Orbital Velocity, Escape Velocity.
  • Electromagnetism: Coulomb's Law, Electric Field, Capacitance (parallel plate), Ohm's Law, Resistor networks (series/parallel), Lorentz Force, Inductor Energy.
  • Thermodynamics: Ideal Gas Law, Carnot Efficiency.
  • Optics: Snell's Law, Thin Lens Formula, Magnification, Critical Angle, Wave Speed, Doppler Effect.
  • Relativity: Time Dilation, Length Contraction, Mass-Energy Equivalence ($E=mc^2$), Schwarzschild Radius.
  • Quantum Mechanics: Photon Energy, Photoelectric Effect, de Broglie Wavelength, Heisenberg Uncertainty Principle, Hydrogen Energy Levels.

5.3 Computer Science & Information Theory

  • Algorithms: Binary Search steps, Merge Sort complexity, Fibonacci (Binet's Formula), Catalan Numbers.
  • Information Theory: Shannon Channel Capacity, Binary Entropy.
  • Machine Learning: Sigmoid Activation, ReLU, Mean Squared Error Loss.
  • Cryptography: RSA Encryption (modular exponentiation placeholder).

5.4 Physical Constants Library

The application includes a dedicated category for Fundamental Physical Constants, hard-coded to high precision:

  • $\pi$ (Pi), $e$ (Euler's number), $\phi$ (Golden Ratio).
  • $G$ (Gravitational Constant), $c$ (Speed of Light), $h$ (Planck Constant), $\hbar$ (Reduced Planck Constant).
  • $k_B$ (Boltzmann Constant), $R$ (Gas Constant), $\epsilon_0$ (Vacuum Permittivity), $\mu_0$ (Vacuum Permeability).
  • $m_e$ (Electron Mass), $m_p$ (Proton Mass), $e$ (Elementary Charge), $N_A$ (Avogadro's Number).

6. User Interface Mechanics

6.1 Graphical User Interface (GUI) Mode

The GUI is built using pure Win32 API calls, avoiding external frameworks.

  • Formula Selection: A COMBOBOX lists all available formulas. Users can scroll or type to search.
  • Dynamic Input Fields: When a formula is selected, UpdateVariableFields() destroys old controls and creates new EDIT boxes and STATIC labels for each variable required by that specific formula. This ensures the UI is always relevant to the selected task.
  • Description Panel: A dedicated label displays the English description of the formula, providing educational context.
  • Calculation Trigger: A "Calculate" button triggers OnCalculate(), which reads inputs, runs the evaluator, and updates the Result label.
  • Context Menu: Right-clicking anywhere in the window opens a Categorized Popup Menu. Formulas are grouped by category (e.g., "Mechanics", "Algebra"), allowing for rapid navigation without scrolling the main combo box.

6.2 Interactive Console Mode

Activated by running sci_calc.exe -i.

  • REPL Loop: Provides a > prompt.
  • Commands:
    • list: Prints all formula names and categories.
    • search <keyword>: Filters formulas by name.
    • info <name>: Displays full details (expression, variables, description).
    • <formula_name>: Initiates an interactive calculation session, prompting for each variable value.
  • Help System: Built-in help command explains usage.

6.3 Command-Line Argument Processing

Activated by running sci_calc.exe <formula> <val1> <val2> ....

  • Batch Processing: Ideal for scripts. For example: sci_calc.exe kinetic_energy 10 5 calculates KE for mass=10, velocity=5.
  • Info Lookup: sci_calc.exe info quadratic_root1 prints the formula details to stdout and exits.
  • Error Handling: Validates argument count against the formula's expected variable count.

6.4 Dynamic Context Menu Generation

The BuildContextMenu() function dynamically constructs the right-click menu at startup:

  1. Iterates through the formulas[] array.
  2. Identifies unique categories.
  3. Creates a submenu for each category.
  4. Appends formula items to their respective submenus.
  5. Assigns unique Command IDs (IDM_CATALOG_BASE + index) to each item.
  6. Handles WM_CONTEXTMENU to display the menu at the cursor position.

7. Execution Flow & Event Loop

  1. Entry Point (WinMain):

    • Checks CommandLineToArgvW.
    • If args > 1: Converts UTF-16 to UTF-8, calls console_main(), and exits.
    • If no args: Registers SciCalcClass, creates the Main Window, and enters the Message Loop.

  2. Message Loop:

    while (GetMessage(&msg, NULL, 0, 0)) {
    TranslateMessage(&msg);
    DispatchMessage(&msg);
}

  3. Window Procedure (WndProc):

    • WM_CREATE: Initializes the ComboBox, Button, Labels, and builds the Context Menu.
    • WM_COMMAND:
      • Handles CBN_SELCHANGE: Updates dynamic variable fields.
      • Handles BN_CLICKED: Runs calculation.
      • Handles Context Menu Selection: Selects formula and updates UI.
    • WM_CONTEXTMENU: Displays the popup menu.
    • WM_DESTROY: Cleans up resources and posts quit message.

  4. Calculation Flow:

    • OnCalculate() -> Reads Edit Controls -> Populates VarEntry Array -> Calls evaluate() -> Formats Result -> Updates Result Label.

8. Performance Optimization Strategies

  1. Pre-compiled Tokens: The tokenizer is highly optimized for speed, using simple character checks and strtod for numbers.
  2. Static Database: The formula database is stored in static memory, requiring no disk I/O or database queries during runtime.
  3. Direct Function Pointers: Built-in functions are called via function pointers, avoiding expensive string comparisons during evaluation.
  4. Efficient Memory Management: The GUI reuses variable input fields where possible, and the parser uses stack-based recursion rather than heap allocation for temporary nodes.
  5. O(1) Category Lookup: The context menu generation uses a simple linear scan with caching to minimize overhead during startup.

9. Extensibility & Future Roadmap

The modular design makes it easy to extend:

  1. Adding New Formulas:

    • Simply add a new entry to the formulas[] array using the F() macro.
    • No code changes are needed in the parser or UI logic.
    • Example: F(new_formula, a*b+c, "a,b,c", 3, "Custom", "My new formula")

  2. Adding New Functions:

    • Implement the C function (e.g., double fn_new(int n, double *a)).
    • Add an entry to the functions[] array.
    • The parser will automatically recognize and support it.

  3. Potential Enhancements:

    • Graphing: Integrate a plotting library to visualize functions.
    • Symbolic Differentiation: Extend the parser to output derivative expressions symbolically.
    • Unit Conversion: Add a unit system to automatically handle conversions (e.g., meters to feet).
    • History Log: Save previous calculations to a file for review.
    • Export: Allow exporting results to CSV or LaTeX.

10. Conclusion

The Scientific Notebook Calculator – Ultimate Edition is a remarkable achievement in lightweight systems programming. By combining a custom recursive descent parser with a vast, structured database of scientific knowledge, it provides a powerful, educational, and efficient tool for technical computation. Its hybrid architecture ensures accessibility across different workflows, from quick CLI checks to detailed GUI-based exploration. Whether used for homework, engineering calculations, or physics research, it stands as a testament to the power of pure C and thoughtful software design.

Disclaimer: While every effort has been made to ensure the accuracy of the formulas and constants, users should verify critical calculations with independent sources. The author assumes no liability for errors resulting from the use of this software.

Built With

  • c
  • cmake
Share this project:

Updates