Crown & Compass logo Crown & Compass Technology Back to GridCalc

GridCalc User Manual (v3.1)

GridCalc User Manual (v3.1)

Thank you for using GridCalc. Questions or feedback: alan@crowncompass.tech.

GridCalc is a persistent, structured RPN calculator built on an execution grid. Every committed action occupies a concrete cell, so the grid itself is the program.

Time is represented left to right, then top to bottom. There is no hidden stack or history view: execution order is spatial and explicit.

Quick Start (60 Seconds)

  1. Press 2, then Enter.
  2. Press 3, then Enter.
  3. Press + to compute 5.
  4. Tap A1 once to inspect it in the HUD and enter EDIT mode.
  5. Change the value, press Enter, and watch downstream cells recompute.
  6. Press REF, then tap a highlighted candidate cell to insert a reference.
  7. Press Fn to access advanced ops, constants, and inverse trig.

1. Core Concepts

1.1 The Grid

  • Fixed size: columns A-F, rows 1-64.
  • Columns stay pinned; rows scroll vertically.
  • Each cell is either empty or one of two kinds: Input or Op.

1.2 The Point and Execution Order

  • The point is the single active position (next write location).
  • On launch and after CLEAR, point is A1.
  • Commits advance the point according to action semantics.
  • Grid motion auto-follows point movement, but manual scrolling can move away.

1.3 Cell Kinds

  • Input: user-entered numeric literal or reference (editable).
  • Op: computed value with operator identity (not directly editable).

1.4 Live vs Consumed

  • Live cells are value-bearing cells still eligible as operands.
  • Consumed cells were already used by an op and are visually muted.
  • Live cells show a thin stack border.
  • Editable live inputs use a brighter live border; computed live values use a softer live border.
  • Operators consume nearest live operands to the left of the point.

2. Modes

2.1 NORMAL

  • Default state for entry and navigation.
  • Type in the entry strip, then press Enter to commit.
  • Enter with an empty buffer advances one empty spacer cell (no-op spacer).

2.2 EDIT (Cell Edit)

  • Enter by single-tapping an editable numeric Input cell.
  • Focus anchors to one editable cell.
  • First numeric key (digit or .) replaces the prior value.
  • First +- also replaces and starts a signed value.
  • Exit with Enter (commit) or CANCEL.

2.3 EDIT LOCK

  • Enter from EDIT by long-pressing the left action key (CANCEL with EDIT caption).
  • Focus stays on one cell across commits.
  • Enter commits and remains locked on that same cell.
  • Exit with CANCEL.

2.4 REF

  • Enter by pressing REF.
  • Select a backward value cell target.
  • One-shot mode exits automatically after commit.

2.5 REF LOCK

  • Enter by long-pressing REF.
  • Commit references repeatedly without leaving ref mode.
  • Exit with CANCEL.

2.6 Keypad Screens

  • 123 and Fn are keypad layouts, not separate compute modes.
  • Switch by tapping the mode key (Fn/123) in the keypad top row.
  • When iOS Reduce Motion is enabled, keypad switching uses a fade transition instead of directional slide.

2.7 STRUCT (Structural Edit)

  • Enter by long-pressing a grid cell to anchor a structural cursor at that address.
  • STRUCT changes grid structure at the structural cursor (insert/delete), not just a cell value.
  • While STRUCT/structural ref picker is active, point styling follows the structural cursor only; the normal trailing point cue is hidden.
  • Enter with an empty structural buffer inserts a blank spacer cell at the cursor and shifts later cells right.
  • Enter with a non-empty structural buffer inserts a value cell at the cursor and shifts later cells right.
  • DEL with an empty structural buffer deletes the cell immediately left of the structural cursor and shifts later cells left.
  • REF in STRUCT opens structural ref picker and commits a reference insertion at cursor.
  • CANCEL exits STRUCT.
  • Operators in STRUCT insert an operator cell at cursor (subject to arity/space guards) and recompute.
  • Structural insert/delete controls are preflight-gated: if an action would create an invalid grid, that control is disabled.
  • Successful structural insert/delete animates moved cells along grid paths (including row wrap) to preserve spatial awareness.
  • This animation is always on. If iOS Reduce Motion is enabled, the app uses reduced-motion variants.

2.8 DEL LOCK (Delete Lock)

  • Enter by long-pressing DEL from NORMAL mode.
  • DEL LOCK highlights only cells that are safe to delete (reference + constructibility guards).
  • Tap a highlighted cell to delete that exact target; later cells shift left and references patch automatically.
  • DEL LOCK stays active for repeated deletes until CANCEL.
  • Non-highlighted cells are inert and cannot be deleted.

2.9 Workspace Panes

  • Use the top GRID/NOTES pane switcher to change workspace.
  • Swipe left/right in the main workspace to switch panes.
  • NOTES is free-form plain text attached to the current sheet.
  • In NOTES, Grid/Entry/Keypad actions are unavailable until you return to GRID.
  • File actions, Settings, and Manual remain available in NOTES.

2.10 Enter Behavior by Mode

  • Normal: commit typed input, or advance one spacer cell if buffer is empty.
  • EDIT: commit edit.
  • EDIT LOCK: commit and stay locked on same cell.
  • REF row picker: commit selected reference when valid.
  • STRUCT: empty Enter inserts a blank spacer; non-empty Enter inserts buffered value at structural cursor.

3. Using GridCalc

3.1 Number Entry and Point Movement

  • Digits and . build the entry buffer.
  • Enter commits to the point as an Input cell and advances point.
  • Empty Enter advances one spacer cell.
  • Tapping a reachable empty cell moves the point there; all cells between current point and target must be empty.

3.2 Sign and Exponent Entry

  • +- toggles the sign of entry/edit buffer.
  • If an exponent (e) is present, +- toggles exponent sign.
  • EE inserts exponent form for scientific input.
  • Empty buffer + EE starts as 1e0 (or -1e0 if already signed).
  • A number accepts only one exponent token.

3.3 Operators

3.3.1 Invocation Rules

  • Operators require sufficient live operands and output space.
  • If typing a valid number, operator press auto-commits that number then applies the operator.
  • In REF entry mode, operators are disabled.
  • In EDIT/EDIT LOCK, all operators are disabled.
  • To run any operator, first finish the edit with ENTER or leave it with CANCEL.

3.3.2 Execution Semantics

  • Scalar ops (+, -, *, /, pow, mod, %, sqrt, trig/logs):
    • Write an Op cell at the point.
    • Consume required nearest live operands to the left.
    • Compute output into that Op cell.
    • Advance point by one cell.
  • Stack transforms (dup, drop, swap, over):
    • Preserve operator identity on emitted outputs.
    • Consume required nearest live operands.
    • drop writes a structural marker carrying dropped source address (for example A1) with DROP badge.
    • Dropped source cell shows a diagonal strike.
    • Other stack transforms: first emitted output occupies action cell; extra outputs are additional Op value cells with same badge.
    • Point advances after emitted outputs.

3.4 Editing and Recompute

  • Single-tap any value cell to inspect it in HUD.
  • Single-tap editable numeric Input to enter EDIT.
  • Edited cell renders draft buffer in-grid until commit.
  • DEL while editing backspaces buffer; first DEL edits existing value in place.
  • Enter commits edit and recomputes downstream dependents deterministically.
  • CANCEL exits edit without committing current draft buffer.
  • Op cells are not editable.
  • Reference inputs can be retargeted or converted to numeric values.

3.4.1 STRUCT Insert/Delete

  • Long-press any address to enter STRUCT anchored to that address.
  • Value insert in STRUCT shifts later cells right and patches references.
  • Structural delete removes the cell immediately left of the structural cursor, shifts later cells left, and patches references.
  • Long-press DEL enters DEL LOCK for targeted delete-by-selection.
  • If insertion has no space (for example the grid tail is full), insert is disabled.
  • If insert/delete would create an invalid operator layout, that action is disabled.
  • Structural edits recompute downstream values after each committed mutation.
  • Successful structural mutations animate moved cells from old slot to new slot. With iOS Reduce Motion enabled, this becomes a brief fade settle.

3.5 References (REF)

3.5.1 Rules

  • Targets must be backward in grid order.
  • Valid targets are value cells: Input or Op value cells.
  • Forward or empty cells are invalid.

3.5.2 Entry Flow

  1. Press REF to enter REF mode.
  2. Tap a highlighted candidate cell, or use picker path.
  3. Picker path: choose column A-F, then valid row number.
  4. Commit occurs automatically once target is valid.
  5. One-shot REF exits after commit.

3.5.3 REF LOCK

  • Long-press REF for REF LOCK.
  • Each commit advances point and remains in ref mode.
  • CANCEL exits lock.
  • While REF/REF LOCK is active, global actions are disabled until CANCEL.

3.5.4 Editing Reference Inputs

  • Tap reference cell once to inspect.
  • Tap same reference again to edit target.
  • Tap another valid target to replace in place.
  • Tap VAL to convert reference input to numeric edit.
  • If converted and committed with no value entered, original reference is preserved.
  • Reference cells display live numeric value plus source badge (for example A1).

3.6 Delete, Undo, Clear

  • DEL while typing/editing: delete one character.
  • DEL in REF row-picker: delete row digits; from empty row buffer returns to column picker.
  • DEL in STRUCT: delete one character from structural buffer; if empty, delete immediately left of the structural cursor.
  • Long-press DEL in NORMAL: enter DEL LOCK and tap highlighted targets for explicit delete.
  • DEL while idle: rewind one semantic action.
  • Deleting stack-transform outputs removes action cell plus emitted op-value cells together.
  • Rewind moves point to earliest deleted position and recomputes.
  • UNDO restores previous semantic state.
  • In EDIT/EDIT LOCK, UNDO is disabled; finish with ENTER or CANCEL first.
  • CLEAR resets grid and point to initial state.

4. Interface and Controls

4.1 HUD and Inspection

  • HUD shows last value (left) and infix preview (right).
  • When a specific cell is inspected, the HUD shows a magnifier marker before the last-value field.
  • Inspected cells get a subtle inspection outline in-grid; this is view-only and does not move the point.
  • When a cell is inspected or in EDIT, reference cells that point to it get a subtle reference highlight.
  • HUD continuity: moving point across empty spacer cells does not clear last-value/infix state.
  • Long-press either HUD field to copy text.
  • Cmd-C copies the cell immediately before the point.

4.2 Keypad

4.2.1 Main Screen (123)

  • Keys: digits, ., +-, Enter, +, -, *, /, EE, DEG/RAD.
  • DEG/RAD toggles angle mode for trig/inverse-trig ops.
  • Trig/inverse-trig ops capture active angle mode at execution time; later mode changes do not reinterpret prior results.

4.2.2 Function Screen (Fn)

  • Row 1: sin, cos, tan, asin, acos
  • Row 2: atan, exp, ln, log10, fact
  • Row 3: pow, dup, drop, swap, over
  • Row 4: pi, e, mod, %, sqrt
  • pi and e write numeric Input values at point and advance one cell.

4.2.3 Top Row Controls

  • Mode toggle (FN/123), UNDO, CLEAR, REF.
  • In ref mode, REF key becomes CANCEL (or VAL when ref picker was entered from EDIT).
  • In reference-edit picker mode, the left action key becomes CANCEL with REF EDIT caption (matching numeric edit affordance style).
  • UNDO/CLEAR are available in Idle only.

4.3 Settings

Open Settings (gear, top bar).

  • Haptics (default on): accepted actions and warnings/errors.
  • Key Clicks (default on): native iOS key click sounds.
  • CRT Point (default off): blinking/glow point border; falls back to static border with Reduce Motion.
  • Zero Key in Middle (default off): swaps bottom-row 0 and +- positions.
  • Number Notation:
    • Auto, Fixed, Scientific, Engineering
  • Digit Grouping:
    • Off, Locale, 3, 3,2
    • Grouping applies to fixed/auto-style display; scientific/engineering use exponent notation formatting.
  • Precision:
    • Fixed: max fractional digits.
    • Scientific/Engineering: max significant digits.
  • Grid Preview Length (default 10): truncates grid cell display with ...; does not change stored/computed values or HUD/infix formatting.
  • Group Input Display (default off): applies grouping to live entry strip.
  • Reset to Defaults: restores display/feedback/keypad settings after confirmation.

Settings apply immediately. Display settings update grid values, HUD last value, and infix preview. Manual view remembers scroll position.

4.4 Notes Pane

  • Switch to NOTES by tapping the top GRID/NOTES pane switcher or swiping left/right across the workspace.
  • NOTES uses the system keyboard and stores plain text.
  • Notes are saved inside the .gridcalc document and participate in dirty/save/autosave behavior.
  • Notes preserve exact text, including whitespace-only content.

4.5 Hardware Keyboard

4.5.1 Entry and Ops

  • Enter: commit input/edit.
  • Delete: backspace or rewind.
  • Esc: cancel ref/edit-lock mode (or plain cell edit).
  • S: toggle sign (+-).
  • E: exponent token (EE).
  • P: insert pi.
  • +, -, *, /, %, digits, .: direct entry/ops.

4.5.2 REF-Specific

  • R: enter ref mode, or cancel ref mode if already active.
  • A-F: choose reference column in ref column-picker.
  • V: convert reference edit target to value (VAL).

4.5.3 File and Clipboard

  • Cmd-Z: undo (Idle only).
  • Cmd-C: copy cell immediately before point.
  • Cmd-V: paste numeric text as new input (Idle only).
  • Cmd-N: new grid.
  • Cmd-O: open file.
  • Cmd-S: save.
  • Tab: toggle keypad screen (123 / Fn) when not editing a cell.

5. Files

Use the Files button (folder icon, top-right) for document actions.

5.1 New

  • Creates blank unlinked Untitled grid (point reset to A1).
  • If current work is unsaved, prompt: Save, Don't Save, Cancel.

5.2 Open

  • Open... selects a file from Files.
  • If current work is unsaved, prompt appears first.

5.3 Save

  • Save writes to linked file.
  • If no linked file exists, behaves as Save As....
  • Linked files autosave while you work.

5.4 Duplicate

  • Duplicate... writes a copy to new location/name.
  • Current linked file stays unchanged.

5.5 Save As

  • Save As... writes to new location/name and links current document there.

5.6 File Status Indicator

  • Status dot beside filename:
    • Green: saved
    • Amber: unsaved changes
    • Blue: saving
    • Red: save error or external conflict
  • Undoing back to last-saved content returns dot to saved state.

5.7 Autosave and Prompts

  • Linked files autosave on short debounce without blocking UI.
  • New/Open usually proceed without unsaved prompt for linked files.
  • Prompts are mainly for:
    • unlinked unsaved work
    • save error/conflict states

5.8 External File Changes

  • If linked file changes outside GridCalc and save is attempted, prompt offers:
    • Reload File
    • Keep Current
    • Duplicate...

5.9 Reopen and Relink (iCloud / Files Authorization)

  • If a previously linked iCloud/Files document needs reauthorization (common after update/reinstall), GridCalc prompts to relink before writing.
  • Prompt actions:
    • Reopen: relink to the same prior file target.
    • Save As...: keep current content and write to a new file target.
    • Not Now: continue without relinking.
  • Until relinked, the document may appear unlinked and Save can route through relink/save-as flow.

6. Limits and Numeric Behavior

6.1 Operational Limits and Errors

  • Grid size is fixed at 6 x 64.
  • Undo history is finite (up to 50 semantic states).
  • If no space remains, commit/insert no-op and point stays at boundary.
  • Invalid numeric text shows Invalid number.
  • Value errors can produce NaN, Inf, -Inf, which propagate forward.
  • fact is enabled only for integer inputs in 0...200.

6.2 Numeric Model

  • GridCalc uses high-precision real-valued math.
  • Notation/grouping/precision change display only, not underlying values.
  • Saved files store values independent of current display settings.
  • NaN represents undefined/non-real outcomes.
  • Inf / -Inf represent signed infinity.
  • Upstream edits/deletes recompute downstream values and can clear prior propagated special values.
  • Typical NaN sources: domain violations (sqrt negative, ln non-positive) and undefined intermediates.

7. Function Reference

Functions consume operands from nearest live values to the left of the point.

7.1 Core Arithmetic

  • + - a b -> (a + b) - addition
  • - - a b -> (a - b) - subtraction
  • * - a b -> (a * b) - multiplication
  • / - a b -> (a / b) - division
  • pow - a b -> a^b - exponentiation
  • mod - a b -> (a mod b) - remainder
  • % - a b -> (a * b / 100) - percent-of
  • sqrt - x -> sqrt(x) - square root (real domain only)
  • fact - n -> n! - factorial, integer domain 0...200

7.2 Trig and Logs

  • sin - x -> sin(x) - sine (uses current DEG/RAD)
  • cos - x -> cos(x) - cosine (uses current DEG/RAD)
  • tan - x -> tan(x) - tangent (uses current DEG/RAD)
  • asin - x -> asin(x) - inverse sine (output follows current DEG/RAD)
  • acos - x -> acos(x) - inverse cosine (output follows current DEG/RAD)
  • atan - x -> atan(x) - inverse tangent (output follows current DEG/RAD)
  • exp - x -> e^x - natural exponential
  • ln - x -> ln(x) - natural logarithm
  • log10 - x -> log10(x) - base-10 logarithm

7.3 Constants

  • pi - -> pi - pi constant
  • e - -> e - Euler’s number

7.4 Stack Transforms

  • dup - x -> x x - append one copy of top live value
  • drop - x -> empty - consume top live value and write non-live provenance marker
  • swap - a b -> b a - consume top two live values and emit reversed order
  • over - a b -> a b a - append one copy of second-from-top live value

8. Glossary

  • Point: active insertion location (next write cell).
  • Live: value-bearing cell still eligible as operand.
  • Consumed: value already used by an operation.
  • Input cell: user-entered numeric literal or reference.
  • Op cell: computed value with operator identity badge.
  • Scalar op: one-cell operation computing into its own Op cell.
  • Stack transform: op that emits one or more value cells and may mark provenance (dup, drop, swap, over).
  • HUD: top strip showing last-value and infix preview.
  • REF mode: one-shot reference insertion mode.
  • REF LOCK: persistent reference insertion mode.
  • EDIT: single-cell edit mode for editable input.
  • EDIT LOCK: persistent edit mode anchored to one editable input.
  • STRUCT: structural insert/delete mode anchored to an explicit structural cursor.
  • DEL LOCK: targeted delete-by-selection mode for safe deletable cells.
  • Linked file: currently attached .gridcalc target for save/autosave.

9. Acknowledgements

GridCalc exists because of the encouragement, support, and love of my wife, Sandra, and the thoughtful testing and early ideation of friends who helped sharpen and refine its direction. In particular, I am grateful to Micha Niskin and Jesse Lundberg for their insight and feedback.

Above all, I give thanks to Jesus Christ, whose grace sustains my life and work.

“Whatever you do, work heartily, as for the Lord and not for men.” - Colossians 3:23