Beta

garcalc

Graphing Calculator with CAS

A graphical calculator with a built-in computer algebra system, 2D and 3D function plotting, parametric and implicit curve support, and a standalone CAS command-line interface. Evaluates expressions symbolically or numerically with support for calculus, linear algebra, and complex numbers.

View on GitHub Install

Features

Symbolic CAS with differentiation, integration, and limits
2D graphing: explicit, parametric, and implicit curves
3D surface plotting with camera rotation and zoom
Exact fractions, complex numbers, and matrix operations
Standalone CAS REPL (garcas) for scripting
Daemon mode with IPC control via garcalcctl
Popup mode for quick calculations from keybindings
Lua and TOML configuration with gar integration
Trace mode for reading values off curves
Viridis, Plasma, Coolwarm, and Grayscale 3D colormaps
Equation solving, simplification, and factoring
Catppuccin-based function color palette

Quick Start Guide

Get up and running with garcalc. This covers installation, the three binaries, and basic usage in each mode.

1. Installation

terminal

$ curl -fsSL https://gar.musicsian.com/install.sh | bash -s -- --component=garcalc # Install via script

$ cd ~/.local/src/gardesk/garcalc && cargo build --release # Or build from source

This builds three binaries: garcalc (GUI), garcalcctl (control client), and garcas (standalone CAS CLI).

2. System Dependencies

garcalc requires Cairo, Pango, and X11 development libraries (via gartk):

Install dependencies

$ sudo pacman -S cairo pango libx11 lua # Arch

$ sudo apt install libcairo2-dev libpango1.0-dev libx11-dev liblua5.4-dev # Debian/Ubuntu

$ sudo dnf install cairo-devel pango-devel libX11-devel lua-devel # Fedora

3. Launch

terminal

$ garcalc # Open calculator (900x600 window)

$ garcalc --popup # Popup mode (centered, closes on focus loss)

$ garcalc --mode graph # Start in 2D graph mode

$ garcalc --mode graph3d # Start in 3D graph mode

$ garcalc --eval "sin(pi/2)" # Evaluate and exit

4. Calculator Mode

Type expressions and press Enter to evaluate. Results appear in the history panel above the input area.

> 2 + 3 * 4
14
> sin(pi/2)
1
> sqrt(2)
1.4142135623730951
> 5!
120
> diff(x^3, x)
3*x^2

5. Graph Mode

Press F2 to switch to 2D graphing. Type a function and press Enter to plot it.

> sin(x)              -- plots y = sin(x)
> x^2 - 3*x + 2       -- plots a parabola
> x^2 + y^2 = 1        -- plots a circle (implicit)
> sin(t), cos(t)       -- plots a circle (parametric)

6. Keyboard Shortcuts

Key	Action
F1	Switch to Calculator mode
F2	Switch to 2D Graph mode
F3	Switch to 3D Graph mode
Return	Evaluate expression
Up / Down	Navigate history
Ctrl+Left / Right	Jump to previous/next word
Home / End	Jump to start/end of input
Escape	Clear input (standalone) or quit (popup)
Ctrl+R	Reset viewport/camera (graph modes)
Ctrl+C	Clear all functions/surfaces (graph modes)
Ctrl+T	Toggle trace mode (2D graph)

Configuration Reference

garcalc reads configuration from the gar Lua config first (~/.config/gar/init.lua), falling back to TOML (~/.config/garcalc/config.toml).

Lua Configuration

~/.config/gar/init.lua

gar.calculator = {
  general = {
    default_mode = "calculator",   -- calculator, graph, graph3d
    precision = 15,                -- decimal precision
    angle_mode = "radians",        -- radians or degrees
    exact_mode = false,            -- symbolic vs numeric results
  },
  popup = {
    width = 700,
    height = 500,
    position = "center",           -- center, topleft, etc.
  },
  graph = {
    x_range = {-10, 10},
    y_range = {-10, 10},
    grid = true,
  },
  appearance = {
    font_family = "monospace",
    font_size = 14,
    button_panel = false,
  }
}

TOML Fallback

~/.config/garcalc/config.toml

[general]
default_mode = "calculator"
precision = 15
angle_mode = "radians"
exact_mode = false

[popup]
width = 700
height = 500
position = "center"

[graph]
default_x_range = [-10.0, 10.0]
default_y_range = [-10.0, 10.0]
grid_enabled = true

[appearance]
font_family = "monospace"
font_size = 14
button_panel_visible = false

General Settings

Option	Default	Description
default_mode	"calculator"	Mode on startup (calculator, graph, graph3d)
precision	15	Decimal digit precision
angle_mode	"radians"	Angle mode for trig functions
exact_mode	false	Keep symbolic results (fractions, sqrt)

Popup Settings

Option	Default	Description
width	700	Popup window width
height	500	Popup window height
position	"center"	Window placement on screen

Graph Settings

Option	Default	Description
default_x_range	[-10, 10]	Initial X-axis viewport
default_y_range	[-10, 10]	Initial Y-axis viewport
grid_enabled	true	Show grid lines on graph

Appearance Settings

Option	Default	Description
font_family	"monospace"	Font for input and history text
font_size	14	Font size in points
button_panel_visible	false	Show on-screen button panel

Overview

garcalc is a graphical calculator for the gardesk desktop environment, inspired by TI-Nspire. It combines a CAS engine for symbolic math with interactive 2D and 3D graphing in a single application.

Architecture

The project is organized as a 9-crate workspace with three binary targets:

Crate	Type	Purpose
garcalc	Binary	Main GUI application with calculator, graph, and 3D modes
garcalcctl	Binary	Control client for the daemon
garcas	Binary	Standalone CAS REPL for scripting
garcalc-cas	Library	Parser, evaluator, symbolic math engine
garcalc-math	Library	Structured math input and typesetting
garcalc-graph	Library	2D and 3D plotting engines (Cairo-based)
garcalc-ipc	Library	JSON IPC protocol types
garcalc-geometry	Library	Dynamic geometry primitives (planned)
garcalc-doc	Library	Multi-page document format (planned)

Modes

Mode	Key	Description
Calculator	F1	Expression evaluation with history
Graph	F2	2D function plotting with pan/zoom/trace
Graph3D	F3	3D surface plotting with camera rotation
Geometry	-	Dynamic geometry (planned)
Spreadsheet	-	Cell-based computation (planned)
Notes	-	Text notes (planned)

Calculator

The default mode shows a history panel with previous calculations and an input area at the bottom. Type an expression and press Enter to evaluate. Use Up/Down arrows to recall previous entries.

Evaluation Modes

Mode	Behavior	Example
Approximate	Evaluates to decimal numbers (default)	1/3 = 0.333...
Exact	Preserves fractions, radicals, and symbols	1/3 + 1/6 = 1/2

Set exact mode in config (exact_mode = true) or via CLI (garcas --exact). The CAS handles integers, rationals, floats, and complex numbers, promoting types as needed.

Expressions

The parser supports standard mathematical notation with operator precedence:

Operator	Description	Example
+, -, *, /	Basic arithmetic	2 + 3 * 4 = 14
^	Power (right-associative)	2^3^2 = 512
!	Factorial (postfix)	5! = 120
=	Equation	x^2 - 1 = 0
[a,b;c,d]	Matrix (semicolons separate rows)	[1,2;3,4]

Number Types

Integers: 42, -7
Rationals: 1/3 (exact mode preserves fractions)
Floats: 3.14, 1.5e-3 (scientific notation)
Complex: 2 + 3*i, sqrt(-1)

Constants

pi	3.14159265358979...
e	2.71828182845904...
i	Imaginary unit
infinity	Positive infinity

Variables

The evaluator maintains a variable environment. In the garcas REPL, assign variables with :=:

x := 5
y := x^2 + 1       -- evaluates to 26
f := sin(x)         -- evaluates using current x value

Undefined symbols are kept symbolic in exact mode, or produce an error in approximate mode.

CAS Engine

The garcalc-cas crate provides a symbolic math engine with an expression AST, recursive descent parser, and evaluator. It supports two evaluation modes:

Approximate mode (default) - Evaluates to numeric results
Exact mode - Preserves symbolic expressions, exact fractions, and radicals

Data Types

The evaluator works with four numeric types, promoting between them as operations require:

Type	Example	Notes
Integer	42, -7, 5!	Arbitrary precision
Rational	1/3, 22/7	Exact fractions (in exact mode)
Float	3.14, 1.5e-3	IEEE 754 double precision
Complex	2+3*i, sqrt(-1)	a + bi form with full arithmetic

The engine also handles vectors (evaluated element-wise), matrices, equations (=), and inequalities (<, >, ≤, ≥, ≠).

Calculus

Function	Description	Example
diff(expr, x)	First derivative	diff(x^3, x) = 3*x^2
diff(expr, x, n)	nth derivative	diff(x^4, x, 2) = 12*x^2
integrate(expr, x)	Indefinite integral	integrate(x^2, x)
integrate(expr, x, a, b)	Definite integral	integrate(x^2, x, 0, 1)
lim(expr, x, a)	Limit	lim(sin(x)/x, x, 0)
sum(expr, n, a, b)	Summation	sum(n^2, n, 1, 10)
product(expr, n, a, b)	Product	product(n, n, 1, 5)

Differentiation applies the chain rule, product rule, and standard derivative rules. Directional limits are supported with a fourth argument: lim(expr, x, a, "left").

Algebra

Function	Description
solve(expr, x)	Solve equation for variable (returns solutions)
simplify(expr)	Algebraic simplification (combine like terms, cancel factors)
expand(expr)	Expand polynomial expressions
factor(expr)	Factor polynomial expressions
subs(expr, var, val)	Substitute variable with value

Matrices

Matrices are entered with square brackets, commas separating columns and semicolons separating rows:

[1, 2; 3, 4]              -- 2x2 matrix
det([1, 2; 3, 4])         -- determinant = -2
inv([1, 2; 3, 4])         -- inverse matrix
transpose([1, 2; 3, 4])   -- transpose
trace([1, 2; 3, 4])       -- trace = 5
matmul(A, B)              -- matrix multiplication
identity(3)               -- 3x3 identity matrix

Explicit Functions

Plot y = f(x) by entering an expression in x. The y = prefix is optional.

sin(x)                 -- sine wave
x^2                    -- parabola
y = x^2 - 3*x + 2     -- with y= prefix
1/x                    -- hyperbola
sqrt(x)                -- square root (x >= 0 only)

Multiple functions can be plotted. Each gets a distinct color from a 6-color Catppuccin palette.

Parametric Curves

Enter two expressions separated by a comma to plot a parametric curve (x(t), y(t)). The default parameter range is [0, 2π].

sin(t), cos(t)             -- circle
(sin(t), cos(t))           -- with parentheses
sin(t), cos(t), 0, pi      -- semicircle (t from 0 to pi)
2*cos(t), sin(t)            -- ellipse

Optional third and fourth comma-separated values set the t range: x(t), y(t), t_min, t_max.

Implicit Curves

Enter an equation with both x and y to plot an implicit curve F(x, y) = 0. The equation is rearranged to lhs - rhs = 0 internally.

x^2 + y^2 = 1       -- unit circle
x^2 + y^2 - 4       -- circle of radius 2 (= 0 implied)
x^2/4 + y^2/9 = 1   -- ellipse

If the input contains y = on the left, it's treated as an explicit function instead.

3D Graphing

Press F3 to enter 3D mode. Enter surfaces as z = f(x, y) or parametric (u, v) expressions.

Explicit Surfaces

sin(x) * cos(y)              -- ripple surface
x^2 + y^2                    -- paraboloid
z = 1 / (1 + x^2 + y^2)     -- bell surface

Parametric Surfaces

sin(u)*cos(v), sin(u)*sin(v), cos(u)    -- sphere
u*cos(v), u*sin(v), u                  -- cone

Mouse Controls

Left drag	Rotate camera (horizontal = azimuth, vertical = elevation)
Scroll wheel	Zoom in/out (1.25x per scroll)

Colormaps

Surfaces are colored by height using one of four colormaps:

Viridis (default) - Perceptually uniform blue-green-yellow
Plasma - Purple-orange-yellow
Coolwarm - Blue-white-red diverging
Grayscale - Black to white

Render Modes

Wireframe - Mesh outline only
Filled - Solid colored surface
Filled + Wireframe - Solid surface with mesh overlay (default)

Default viewport is [-5, 5] for all axes. Camera starts at 45° azimuth, 30° elevation, 25 units distance. Elevation is clamped to ±89°. Mesh resolution is 40 grid lines. Use Ctrl+R to reset.

IPC Protocol

The daemon listens at $XDG_RUNTIME_DIR/garcalc.sock for JSON commands.

Commands

{"command": "show"}
{"command": "hide"}
{"command": "toggle"}
{"command": "evaluate", "expr": "sin(pi/2)"}
{"command": "get_mode"}
{"command": "set_mode", "mode": "graph"}
{"command": "status"}
{"command": "quit"}

Responses

{"success": true}
{"success": true, "data": {"type": "evaluation", "input": "2+2", "result": "4"}}
{"success": true, "data": {"type": "mode", "mode": "calculator"}}
{"success": true, "data": {"type": "status", "visible": true, "mode": "calculator", "history_count": 5}}
{"success": false, "error": "Parse error at position 3"}

garcalcctl

Command-line client for the garcalc daemon:

Command	Description
show	Show the calculator window
hide	Hide the calculator window
toggle	Toggle window visibility
eval <EXPR>	Evaluate expression and print result
mode [MODE]	Get or set calculator mode
status	Get daemon status
quit	Stop the daemon

$ garcalcctl eval "diff(x^2, x)" # Evaluate via daemon

$ garcalcctl mode graph # Switch to graph mode

$ garcalcctl status # Check daemon status

Common Workflows

Keybinding with gar

Launch garcalc as a popup from a keybinding:

~/.config/gar/init.lua

-- Calculator popup (toggle with Super+C)
gar.bind("mod+c", function() gar.exec("garcalcctl toggle") end)

-- Or launch directly as popup
gar.bind("mod+c", function() gar.exec("garcalc --popup") end)

Quick Evaluation from Shell

$ garcalc -e "2^10" # 1024

$ garcas -e "diff(sin(x)*cos(x), x)" # Symbolic derivative

$ garcas --exact -e "1/7 + 2/7" # 3/7 (exact fraction)

Daemon Mode for Instant Access

Run the daemon at login, then toggle the window from keybindings:

$ garcalc --daemon & # Start daemon in background

$ garcalcctl toggle # Show/hide calculator window

$ garcalcctl eval "sqrt(2)" # Evaluate without showing window

Scripting with garcas

Use garcas in shell scripts:

math.sh

#!/bin/bash
# Batch evaluate expressions
while IFS= read -r expr; do
    result=$(garcas -q -e "$expr")
    echo "$expr = $result"
done < expressions.txt

Plotting Multiple Functions

In graph mode, enter multiple functions one at a time. Each gets a different color:

> sin(x)       -- blue
> cos(x)       -- green
> tan(x)       -- yellow
-- Pan with left drag, zoom with scroll wheel
-- Ctrl+R to reset viewport, Ctrl+C to clear all

Troubleshooting

garcalcctl: connection refused

The daemon isn't running:

$ pgrep -x garcalc # Check if daemon is running

$ ls -la ${XDG_RUNTIME_DIR:-/tmp}/garcalc.sock # Check socket

$ garcalc --daemon & # Start daemon

Popup window doesn't close on click outside

Popup mode closes on focus loss. If your window manager doesn't send focus events for override-redirect windows, use the daemon with garcalcctl toggle instead.

Expression returns wrong result

Check angle mode (radians vs degrees):

$ garcas -e "sin(90)" # Returns 0.894... (radians)

$ garcas --angle degrees -e "sin(90)" # Returns 1 (degrees)

Graph not displaying

Ensure you're in graph mode (F2 for 2D, F3 for 3D). Check that the function evaluates without errors. Use Ctrl+R to reset the viewport if zoomed too far.

Exact mode not preserving fractions

Exact mode must be enabled in config or via CLI flag. Check that the config is being loaded:

$ garcas --exact -e "1/3 + 1/6" # Should return 1/2

$ garcas -e "1/3 + 1/6" # Returns 0.5 (approximate mode)

Window appears but is blank

Verify Cairo and X11 are working. Check that gartk dependencies are installed:

$ pkg-config --modversion cairo # Should print Cairo version

$ pkg-config --modversion pangocairo # Should print Pango version

Config not loading

garcalc reads Lua config first, then falls back to TOML. Check both paths:

$ cat ~/.config/gar/init.lua | grep calculator # Check Lua config

$ cat ~/.config/garcalc/config.toml # Check TOML fallback

$ RUST_LOG=debug garcalc 2>&1 | grep config # See which config is loaded

Debug logging

Enable verbose output:

$ RUST_LOG=debug garcalc # Debug mode

$ RUST_LOG=trace garcas # Trace CAS evaluation

Releases

v0.1.0 Initial Release

• CAS engine with symbolic differentiation, integration, limits, and summation
• 2D graphing: explicit, parametric, and implicit curves
• 3D surface plotting with camera rotation and zoom
• Exact fractions, complex numbers, and matrix operations
• Standalone CAS REPL (garcas) for scripting
• Daemon mode with IPC control via garcalcctl
• Popup mode for quick calculations from keybindings

Back to home

Left drag	Pan viewport
Scroll wheel	Zoom in/out (1.1x per scroll, centered on cursor)
Right click	Toggle trace mode (shows function value at cursor)

quit / exit / q	Exit the REPL
help / ?	Show help with all functions
clear	Clear all variables
x := expr	Assign variable

garcalc

Features

Quick Start Guide

1. Installation

2. System Dependencies

3. Launch

4. Calculator Mode

5. Graph Mode

6. Keyboard Shortcuts

Configuration Reference

Lua Configuration

TOML Fallback

General Settings

Popup Settings

Graph Settings

Appearance Settings

Overview

Architecture

Modes

Calculator

Evaluation Modes

Expressions

Number Types

Constants

Functions

Trigonometric

Hyperbolic

Exponential & Logarithmic

Roots & Rounding

Number Theory & Aggregation

Variables

CAS Engine

Data Types

Calculus

Algebra

Matrices

2D Graphing

Plot Types

Mouse Controls

Rendering

Explicit Functions

Parametric Curves

Implicit Curves

3D Graphing

Explicit Surfaces

Parametric Surfaces

Mouse Controls

Colormaps

Render Modes

garcas CLI

REPL Commands

Daemon & IPC

IPC Protocol

Commands

Responses

garcalcctl

Common Workflows

Keybinding with gar

Quick Evaluation from Shell

Daemon Mode for Instant Access

Scripting with garcas

Plotting Multiple Functions

Troubleshooting

garcalcctl: connection refused

Popup window doesn't close on click outside

Expression returns wrong result

Graph not displaying

Exact mode not preserving fractions

Window appears but is blank

Config not loading

Debug logging

Releases