NAPKIN / LANGUAGE REFERENCE

A few lines of engineering.

A .napkin file describes quantities, equations, geometry, and checks. Napkin turns it into a study with stable references and unit-aware calculations.

Write the question down.

Form	Example	Meaning
Input	`length = 300 mm in 100..500`	An editable quantity, its unit, and an optional design range.
Derived quantity	`inertia := width * depth^3 / 12 [mm^4]`	An equation bound to other quantities. The bracket declares the result unit.
Unknown	`flow ?= 10 L/min`	An initial guess for an unknown solved by declared relations.
Relation	`relate balance: inlet == outlet ± 0.01 L/min`	A residual and a tolerance for the solver.
Check	`check bend: deflection <= 2 mm`	An observation and a requirement, evaluated for each scenario.
Part	`part beam "Cantilever": box length, width, depth`	Geometry linked to quantity references.
Scenario	`scenario more reach: length = 500 mm`	Input overrides evaluated without changing the baseline.
Function	`roadLoad(v: m/s) := 12 N + 0.5 kg/m * v^2 [N]`	A unit-aware function with explicit arguments.
Measured curve	`head(Q: L/min) [m] := table 0: 25, 300: 12.5`	A piecewise-linear table with argument and output units.
Sweep	`sweep reach: length = 100..500 x 5 mm`	A scalar design sweep for a full study.

Blank lines and whole-line # or // comments are ignored. A quoted string records an assumption or label. Trailing tags such as #mass group quantities. Indentation introduces component options and duty-cycle profile segments.

Constants and symbols

pi and e are the two built-in mathematical constants: pi is the circle constant (approximately 3.14159), and e is the base of natural logarithms (approximately 2.71828). Both are dimensionless and evaluated numerically; Napkin does not provide exact symbolic algebra.

Declare engineering reference values with const, a value, units, and an explanatory note. A constant is a shared input: copied parts can retain the same quantity reference, and automatic sensitivity selection skips it. It remains editable and can be explicitly selected for analysis; const does not lock or certify a value.

const g0 = 9.80665 m/s^2 "Standard gravity; reference value"
mass = 10 kg
weight := mass*g0 [N]
radius = 10 mm
circleArea := pi*radius^2 [mm^2]
naturalBase := e
rho = 2700 kg/m^3 "Illustrative density; verify the material"

rho and phi have no built-in values. Names use ASCII letters, digits and underscores, beginning with a letter or underscore. Declare overloaded engineering symbols with their intended meaning and units. Material properties and empirical coefficients also need applicable conditions and a trustworthy source; a quoted note records an assumption, not an independently verified citation.

Built-in functions

Group	Functions	Behavior
Trigonometry	`sin(x), cos(x), tan(x)`	Use angles in deg or rad. Plain numbers are radians.
Inverse trigonometry	`asin(x), acos(x), atan(x), atan2(y, x)`	Inputs are dimensionless. Results can be declared in deg or rad. For dimensional coordinates, normalize both atan2 arguments by the same reference quantity.
Powers and magnitude	`sqrt(x), abs(x)`	Square root and absolute value; resulting dimensions must match the declared output unit.
Exponential and logarithms	`exp(x), log(x), log10(x)`	Dimensionless arguments. log is the natural logarithm; log10 is base ten.
Bounds	`min(a, b), max(a, b)`	Arguments must have compatible units.
Rounding and sign	`floor(x), ceil(x), round(x), sign(x)`	Floor, ceiling, nearest-integer rounding and sign. Normalize dimensional values before rounding.

Angles and trigonometry

Use deg or rad for angle inputs. Trigonometric calculations normalize angles to radians. An unlabelled number is interpreted in radians; inverse trig results can declare either angle unit. For atan2, the current evaluator requires dimensionless arguments, so normalize coordinates by the same reference quantity first.

length = 200 mm
angle = 30 deg
rise = 100 mm
run = 200 mm
vertical := length*sin(angle) [mm]
horizontal := length*cos(angle) [mm]
inclination := atan(rise/run) [deg]
bearing := atan2(rise/run, 1) [deg]
unitSine := sin(pi/6)

Other mathematical functions

root := sqrt(9)
magnitude := abs(-3)
decay := exp(-1)
naturalLog := log(e)
decimalLog := log10(1000)
bounded := min(10, max(0, -2))
down := floor(2.8)
up := ceil(2.2)
nearest := round(2.6)
direction := sign(-2)

Arithmetic supports + - * / ^ and parentheses. Expressions also support comparisons < <= > >= == !=, boolean operators and or not, and conditionals such as load > 0 N ? load : 0 N. These expression comparisons are distinct from a check declaration, whose requirement uses < <= > >=. Assignment, property access, arrays and arbitrary JavaScript calls are not permitted. To define your own reusable relation, use the Function declaration.

Units and conversions

Inputs carry units after the value. Declare a derived output unit in square brackets. Compatible quantities convert automatically during calculation; incompatible dimensions reject the edit. The table lists common supported spellings, not every possible unit.

Quantity	Supported examples
Length	`nm, um, mm, cm, m, km, inch, ft, yd, mile`
Area and volume	`mm^2, m^2, cm^3, m^3, L, mL, gal`
Mass	`mg, g, kg, lb, oz`
Time	`ns, us, ms, s, min, h, day, year`
Angles and rates	`deg, rad, rpm, rps, Hz`
Force and pressure	`N, kN, lbf, Pa, kPa, MPa, GPa, bar, psi`
Energy and power	`J, kJ, Wh, kWh, W, kW, hp`
Electrical and magnetic	`V, mV, A, mA, uA, ohm, kohm, F, uF, nF, pF, H, mH, uH, C, Ah, T, mT, Wb`
Temperature	`K, degC, degF`
Photometry and amount	`cd, sr, lm, lux, lx, mol`
Dimensionless	`No unit, or percent (85 percent equals 0.85)`
Compound units	`kg/m^3, m/s^2, Nm, W/(mK), J/(kg*K), ft^3/min`

Use *, / and ^ for compound units and powers. Prefixes and unit names are case-sensitive: mW and MW are different. Use the verified ASCII spellings um, ohm and degC shown here.

length = 12 inch
metricLength := length [mm]
speed = 3000 rpm
omega := speed [rad/s]
period := 2*pi/speed [s]
frequency := 1/period [Hz]
torque = 2 N*m
shaftPower := torque*speed [W]
ambient = 25 degC
rise = 13 K
temperature := ambient+rise [degC]
efficiency = 85 percent
inputPower = 100 W
outputPower := efficiency*inputPower [W]

Conventions and current limitations

Mass and force: kg and lb are mass; N and lbf are force. Convert between mass and weight using an explicit gravitational acceleration.
Temperature: degC and degF are absolute temperature scales with offsets. Use K for differences and absolute temperatures in radiation or ideal-gas equations.
Rotation and frequency: shaft speeds use rpm, rps or rad/s. Frequency uses Hz. Direct angular-rate conversions to Hz or reciprocal seconds are rejected as ambiguous; for revolution frequency, derive a period with period := 2*pi/speed [s], then use frequency := 1/period [Hz].
Logarithmic quantities: dB and dBm are not recognized unit tokens. Calculate logarithmic ratios explicitly with log10 and state the reference. CFM is not recognized; use ft^3/min.
Minutes in checks: min is a supported time unit, but a check ending in min currently conflicts with the aggregation keyword. Write a threshold such as 120 s instead of 2 min in checks until this parser ambiguity is fixed.
Physical validity: compatible dimensions do not establish the correct physical model. State assumptions, input ranges and uncertainty, and verify important results.

From text to an engineering model.

Parse. Each declaration becomes a typed record: a quantity, part, relation, observation, scenario, or component.
Bind. Names in equations resolve to stable references such as sketch:length. Forward references are allowed.
Validate and commit. The study checks units, references, and model constraints, then applies the records as one revision-checked edit.
Evaluate. Derived quantities follow their dependencies. Scenarios override inputs; the baseline stays intact.
Check and present. The engine compares observations with the limits in the source. The website formats those values and verdicts.

Inspect the records generated from cantilever.napkin

These are the parser’s actual records for the length, beam, deflection, check, and longer-reach scenario. Notice how equations and geometry refer to the same quantity IDs.

[
  {
    "id": "sketch:length",
    "kind": "quantity",
    "spec": {
      "name": "length",
      "role": "input",
      "unit": "mm",
      "value": {
        "value": 300,
        "unit": "mm"
      },
      "range": [
        {
          "value": 100,
          "unit": "mm"
        },
        {
          "value": 500,
          "unit": "mm"
        }
      ]
    }
  },
  {
    "id": "sketch:beam",
    "kind": "part",
    "spec": {
      "name": "Cantilever",
      "geometry": {
        "kind": "box",
        "size": [
          {
            "id": "sketch:length",
            "kind": "quantity"
          },
          {
            "id": "sketch:width",
            "kind": "quantity"
          },
          {
            "id": "sketch:depth",
            "kind": "quantity"
          }
        ]
      },
      "pose": {
        "position": [
          {
            "value": 0,
            "unit": "m"
          },
          {
            "value": 0,
            "unit": "m"
          },
          {
            "value": 0,
            "unit": "m"
          }
        ],
        "quaternion": [
          0,
          0,
          0,
          1
        ]
      }
    }
  },
  {
    "id": "sketch:deflection",
    "kind": "quantity",
    "spec": {
      "name": "deflection",
      "role": "derived",
      "unit": "mm",
      "expression": {
        "text": "load * length^3 / (3 * modulus * inertia)",
        "bindings": {
          "load": {
            "id": "sketch:load",
            "kind": "quantity"
          },
          "length": {
            "id": "sketch:length",
            "kind": "quantity"
          },
          "modulus": {
            "id": "sketch:modulus",
            "kind": "quantity"
          },
          "inertia": {
            "id": "sketch:inertia",
            "kind": "quantity"
          }
        },
        "unit": "mm"
      }
    }
  },
  {
    "id": "sketch:check:tip deflection",
    "kind": "observation",
    "spec": {
      "name": "tip deflection",
      "query": {
        "kind": "expression",
        "expression": {
          "text": "deflection",
          "bindings": {
            "deflection": {
              "id": "sketch:deflection",
              "kind": "quantity"
            }
          },
          "unit": "mm"
        }
      },
      "check": {
        "comparison": "<=",
        "limit": {
          "value": 2,
          "unit": "mm"
        }
      }
    }
  },
  {
    "id": "sketch:scenario:more reach",
    "kind": "scenario",
    "spec": {
      "name": "more reach",
      "overrides": [
        {
          "quantity": {
            "id": "sketch:length",
            "kind": "quantity"
          },
          "value": {
            "value": 500,
            "unit": "mm"
          }
        }
      ]
    }
  }
]

The landing-page editor recalculates a temporary study after each edit. It does not save your source or change your account’s studies. It supports a baseline and up to six simple scenarios; use the full Napkin tools for sweeps and profiles.

Source and saved studies.

Use napkin_source to read, validate and apply a complete source document. Applying complete source replaces its owned records, including removed lines; napkin_sketch applies additive fragments. In the Study editor, drafts preview before Apply source saves them. Revision checks preserve concurrent edits.

.napkin is engineering source. Complete study documents remain JSON and can also include scenes, images, annotations, and presentation state. The text syntax does not yet serialize every part of a saved study.

These are analytical models for early design. Dynamic simulation and general assembly pose solving are not shipped. Inspect assumptions and cross-check important results.

Download the cantilever example ↓

A complete study

This rover model connects inputs, equations, scenarios and engineering checks.

const g = 9.80665 m/s^2
payload = 40 kg in 0..500 "Rated cargo"
grade = 0.08 in 0..0.6 "Rise over run"
chassis = 25 kg
mass := chassis + payload [kg]
weight := mass*g [N]
climbForce := weight*grade [N]
wheelD = 0.3 m
climbTorque := climbForce*wheelD/2 [N*m]
check motor torque: climbTorque <= 15 N*m
scenario Steep: grade = 0.15, payload = 80 kg

All line types

Input

A number you choose or assume. A range sets the design interval; a tolerance sets the uncertainty; the quoted note records why.

FORM

key = value unit [in min..max] [± tol%] ["assumption"]

EXAMPLE

payload = 40 kg in 0..500 ± 10% "Rated cargo"

Constant

A shared input or reference value, not an immutable mathematical constant. It is retained when copying dependent parts and excluded from automatically selected sensitivity inputs; it remains editable.

FORM

const key = value unit

EXAMPLE

const g = 9.80665 m/s^2

Derived quantity

A value computed from other keys. Units are checked; a mismatch rejects the edit. Tags group quantities for rollups.

FORM

key := expression [unit] [#tag]

EXAMPLE

chassis = 12 kg
payload = 40 kg
mass := chassis + payload [kg] #mass

Rollup

Sums, or takes the extreme of, every quantity with a tag.

FORM

key := sum|min|max of tag [unit]

EXAMPLE

frame = 3 kg #mass
battery = 2.5 kg #mass
total := sum of mass [kg]

Function

A reusable physics relation, called like f(x) elsewhere.

FORM

name(arg: unit, …) := expression [unit]

EXAMPLE

crr = 0.015
mass = 60 kg
const g = 9.80665 m/s^2
rho = 1.2 kg/m^3
cda = 0.6 m^2
roadLoad(v: m/s) := crr*mass*g + 0.5*rho*cda*v^2 [N]

Table

A measured curve, such as a pump or motor datasheet, interpolated linearly.

FORM

name(arg: unit) [unit] := table x: y, x: y, … ["source"]

EXAMPLE

curve(Q: L/min) [m] := table 0: 25, 150: 21.9, 300: 12.5 "Datasheet"

Unknown and relation

A value Napkin solves for, such as an operating point where two curves meet.

FORM

key ?= guess unit in min..max · relate name: lhs == rhs ± tol unit

EXAMPLE

voltage = 24 V
kv = 100 rpm/V
speedAt(v: m/s) := v/(0.1 m)*1 rad [rad/s]
vTop ?= 3 m/s in 0.01..30
relate top: speedAt(vTop) == 0.95*voltage*kv ± 0.001 rad/s

Check

A requirement. It passes or fails on every run, sweep sample and scenario.

FORM

check name: expression <=|>=|<|> limit

EXAMPLE

range = 12 km
check range: range >= 10 km

Probe

A value to report from a run, optionally aggregated over time.

FORM

probe name: expression [unit] [instant|min|max|mean|rms|integral]

EXAMPLE

power = 250 W
probe energy: power [W] integral

Scenario

A load case: overrides on top of the baseline inputs.

FORM

scenario Name: key = value, …

EXAMPLE

grade = 0.08
payload = 40 kg
scenario Steep: grade = 0.15, payload = 80 kg

Sweep

Run the study across a range of one input.

FORM

sweep Name: key = from..to x count unit  (or a list: a, b, c unit)

EXAMPLE

speed = 2 m/s
sweep Speeds: speed = 1..3 x 5 m/s

Duty profile

A duty cycle. Probes can take time-weighted means and integrals over it.

FORM

profile Name: then indented segments: label duration: overrides

EXAMPLE

sun = 1
profile Day:
  night 15 h: sun = 0
  noon 3 h: sun = 0.4

Component catalog

Catalog parts for inputs that already exist. Scenarios select an option by name; analyses compare them.

FORM

component key "Name": field, field, … then one indented line per option

EXAMPLE

kv = 920 rpm/V
R = 0.12 ohm
mass = 55 g
component motor "Motor": kv, R, mass
  2216 920Kv: 920 rpm/V, 0.12 ohm, 55 g "Datasheet A"
  2814 700Kv: 700 rpm/V, 0.09 ohm, 96 g "Datasheet B"

Part

Geometry for the linked drawings. Values are numbers with units or keys. Cylinders run along their local z axis; rotations are in degrees.

FORM

part key "Name": box x, y, z | cylinder r, length | capsule r, length | sphere r [at x, y, z] [rot X, Y, Z]

EXAMPLE

wheelR = 0.12 m
axleX = 0.4 m
part wheel "Wheel": cylinder wheelR, 0.06 m at axleX, 0.25 m, wheelR rot 90 deg, 0 deg, 0 deg

Rules

Keys start with a letter or underscore; source records use stable IDs of the form prefix:key.
Units are checked throughout. Inspect assumptions and output units before relying on results.
Functions and tables are callable; they are not scalar input fields.
A failed engineering check is a valid calculated result. Invalid source leaves the saved Study unchanged.
Read the current revision before applying a saved change.