Calculator Engine Reference

Documentation map

This documentation is organized to mirror the engine pipeline and then dive into the full function library.

1. Start with the engine overview and evaluation model.
2. Learn syntax rules and preprocessing (implicit multiplication, degree symbol, polar notation).
3. Understand display modes and formatting controls.
4. Study the routing rules that decide numeric vs symbolic evaluation.
5. Use the complete function catalog and constants lists.
6. Review edge cases and limitations for reliable results.

Engine overview

GrayCalc uses a dual-engine approach:

• Numeric engine for fast numeric evaluation and matrix operations.
• Symbolic engine (running in-browser in a Web Worker) for algebra, calculus, transforms, and advanced solving.

The engine automatically routes each line to the appropriate engine based on the expression and current variable context. The symbolic engine is loaded on demand; the first symbolic evaluation may take a few seconds while it initializes.

Quick start

Open the app, start a new sheet, and paste this mini worksheet. Each line evaluates independently, and later lines can reference variables from earlier lines.

2 + 3 * 4
(2 + 3) * 4
2^8

a = 5
b = 12
c = sqrt(a^2 + b^2)
c

v = [10, 20, 30]
v[0]

solve(x^2 - 4, x)

• Edit a or b and watch c update automatically.
• Try v[2] to grab the last list element (indexing is 0-based in the UI).

Next: Evaluation model, Syntax, Engine routing, Function catalog.

Evaluation model

• Each line is evaluated independently but can reference variables from earlier lines.
• Variables are scoped by line number. A variable defined later does not affect earlier lines.
• Editing a line re-evaluates dependent lines automatically.
• Lines starting with # are treated as comments and produce no output.

a = b + 2
c = a^2

Syntax & preprocessing

Operators and precedence

• Exponentiation: ^ (e.g., 2^8).
• Multiplication and division: *, /.
• Addition and subtraction: +, -.
• Parentheses control order of operations.
• Assignment uses a single = (e.g., a = 5).

Implicit multiplication

GrayCalc inserts multiplication automatically in common cases:

• 2x is interpreted as 2 * x.
• 3(y + 1) is interpreted as 3 * (y + 1).
• )x and )2 insert multiplication after the closing parenthesis.

Variable names

• Pattern: [A-Za-z_][A-Za-z0-9_]*.
• Greek letters are supported in variable names.
• Names are case-sensitive (g and G are different constants).

Degree symbol

Degree notation is supported with °:

• In radian mode, 90° becomes toRadians(90).
• In degree mode, 90° stays numeric because trig functions expect degrees.

sin(90°)

Polar angle notation

Polar complex numbers use the ∠ symbol:

10 ∠ 45°

This is converted to (10) * exp(i * (45°)), with automatic degree-to-radian conversion when angle mode is degrees.

Complex numbers

• Use i as the imaginary unit: 3 + 4i.
• Polar display mode formats results as r∠theta.
• Rectangular display mode formats results as a + bi.

Indexing (0-based)

Array and matrix indexing is 0-based in the UI:

v = [10, 20, 30]
v[0]

Matrix indexing uses [row, col]:

M = [[1, 2], [3, 4]]
M[0, 1]

Internally, indexes are shifted to match the 1-based indexing used by the numeric engine.

Modes & formatting

Angle mode

• Radians (rad) is the default.
• Degrees (deg) changes trig functions to interpret inputs as degrees.
• Inverse trig functions return values in the current angle mode.

Complex display mode

• Rectangular: a + bi.
• Polar: r∠theta (theta in degrees when angle mode is degrees).

Number display mode

• Decimal: numeric output is formatted as decimals.
• Fraction: numeric output is formatted as rational fractions.

Calculation format and precision

• Format options: auto (plain decimal, no scientific notation), fixed, exponential (scientific), engineering.
• Decimal places range: 0-14.

Formatting uses the numeric engine formatter and respects the current mode.

Engine routing

The engine decides whether to evaluate a line in the numeric engine or symbolic engine using clear rules:

1. Explicit symbolic commands always route to the symbolic engine (see list below).
2. Undefined symbols route to the symbolic engine to preserve structure.
3. Symbolic dependencies (variables defined symbolically earlier) route to the symbolic engine.
4. Numeric-only expressions stay in the numeric engine for speed.
5. If the numeric engine fails to evaluate a line, the engine falls back to the symbolic engine (when enabled).

Symbolic engine details

Raw symbolic input

Prefix a line with symbolic: to send raw Python directly to the worker.

symbolic: sp.N(erf(1))

Default arguments

• laplace(expr) expands to laplace(expr, t, s).
• inverse_laplace(expr) expands to inverse_laplace(expr, s, t).
• diff(expr) defaults to x (or t if t appears).
• integrate(expr) defaults to x (or t if t appears).
• integrate(expr, v, a, b) rewrites to integrate(expr, [v, a, b]).
• integral(expr, v, a, b) is an alias for integrate(expr, [v, a, b]).
• derivative(expr, v, at) is an alias for diff(expr, v).subs(v, at).
• nsolve(eq, var, [guess]) defaults the initial guess to 1 when omitted.

Solving equations with equals sign

For solve and linsolve, lists of equations can use = and are rewritten to Eq(...) automatically:

solve([x + y = 2, x - y = 0], [x, y])

Symbol creation and substitutions

• Unknown identifiers are auto-defined as symbolic variables.
• Variables from earlier lines are substituted into symbolic results where applicable.
• Symbolic results display with ** converted to ^. When storing into the numeric engine, I is converted to i.

User-defined functions

GrayCalc supports lightweight Python-style function definitions.

Multi-line functions

def f(x):
  y = x^2 + 1
  return y

• Indentation is required for the body.
• Supported statements: assignments, return, and condition headers (if/elif/else).
• Control flow is limited (conditions are evaluated but do not run full branches).

Single-line functions

f(x) = x^2 + a

Single-line definitions are registered as functions with a single return expression.

Variables & dependencies

• Variables are tracked with line numbers to preserve notebook order.
• When a variable changes, all dependent lines are marked for re-evaluation.
• Deleting a line removes variables defined on that line from the active scope.

Unit-like identifiers

Inline units are not parsed. Identifiers like m, cm, and kg are treated as symbolic variables first.

Symbolic example

5 m + 200 cm

Explicit conversions

convert(60, "mi/h", "m/s")

Constants

Math constants

• pi = 3.141592653589793
• e = 2.718281828459045
• i = imaginary unit
• tau = 2 * pi
• phi = 1.618033988749895 (Golden ratio)
• eulerGamma = 0.5772156649015329
• sqrt2 = 1.4142135623730951
• sqrt3 = 1.7320508075688772
• sqrt5 = 2.23606797749979

Physical constants

• hbar = 1.0545718176461565e-34 (J*s)
• k_B = 1.380649e-23 (J/K)
• N_A = 6.02214076e23 (mol^-1)
• epsilon_0 = 8.8541878128e-12 (F/m)
• mu_0 = 1.25663706212e-6 (H/m)
• e_charge = 1.602176634e-19 (C)
• m_e = 9.1093837015e-31 (kg)
• m_p = 1.67262192369e-27 (kg)

Engineering constants

• atm = 101325 (Pa)
• bar = 100000 (Pa)
• psi = 6894.757 (Pa)
• fahrenheit = 32
• celsius = 0
• kelvin = 273.15

Function catalog

This catalog lists the core numeric-engine functions surfaced by GrayCalc plus all custom helpers. The numeric engine exposes additional functions beyond this list. Functions marked "Symbolic engine" route to the symbolic engine.

Basic math & algebra

Trigonometry (angle-mode aware)

Complex numbers

Statistics

Finance & business

Engineering

Physics

Chemistry & biology

Project management

Computer science

Numerical methods

Differential equations

Transform theory

Series & expansions

Linear algebra

Signal processing

Control systems

Plotting

Utility & combinatorics

Symbolic algebra

Edge cases & limitations

• Inline comments are not supported. Comments must start the line.
• Multi-letter identifiers are treated as one variable. Use explicit * when you want multiplication.
• Python-style function bodies support assignments and returns; full control flow (loops, multi-branch if) is not implemented.
• Symbolic commands can be expensive for large expressions; the symbolic engine may take a moment to initialize.
• bode uses complex evaluation internally but the current transfer-function implementation is numeric-only, so results may be NaN. Use the symbolic engine for complex frequency responses.
• Alias spellings such as integral, derivative, invLaplace, ztransform, and invZtransform are normalized to their symbolic equivalents before evaluation.