The Calcpad language

Description

Calcpad uses a simple programming language for the development of engineering worksheets. It mostly includes mathematical expressions, mixed with text/Html comments. Some advanced options for conditional execution, iterations, units and numerical methods are also available. Detailed description is provided in the user manual. Bellow, you can find a quick reference guide:

Expressions

Constants

Real

All real values are stored in double precision floating point fields. They can range from -1.7976931348623157E+308 to 1.7976931348623157E+308. The smallest nonzero value is 4.94065645841247E-324. Smaller values are considered exactly zero. You can use the following input formats:

Format	Positive	Negative
Integer	34	-34
Decimal	3.45	-3.45
Fraction	3/4	-3/4
Exponential	3.4`*`10`^`5	-3.4`*`10`^`5

The last two formats are nothing but simple expressions.

Complex

Complex numbers are represented by a couple of values ±a ± bi, where “a” is the real part, and “bi” is called “imaginary”. The imaginary unit in Calcpad is entered as 1i. It is defined so that (1i)^2 = -1. You must switch to “Complex” mode in order to use complex numbers.

Predefined

There are four predefined constants that are stored as named variables:
e = 2.71828182845905 – the base of the natural logarithms (Euler’s number);
π = 3.14159265358979 – (Pi) the ratio of circumference to diameter of a circle;
g = 9.80665 – the gravitational acceleration on Earth;
i = 1i – the imaginary unit.

Variables

Variable names can contain Latin and Greek letters, digits, commas “,”, underscores “_” and some special symbols: ” ′, ″, ‴, ⁗, ø, Ø, °, ∡”. The first character must be a letter. The underscore is used to start a subscript. Variables are created by assigning a value, e.g.:
a_1 = 2

Operators

You can use the following operators with Calcpad:

Symbol	Description
!	factorial
^	exponent
/	division
÷	division bar
*	multiplication
–	subtraction
+	addition
\	integer division
%	reminder
≡	equal
≠	unequal
<	less than
>	greater than
≤	less or equal
≥	greater or equal
=	assignment
?	input field

Instead of special symbols for comparrision operators ≡ ≠ ≤ ≥, you can use C/C++ style shortcuts, respectively: ==, !=, <=, >=.

Functions

Built-in

The following functions are predefined and can be used directly:

Name	Description
abs(x)	absolute value (modulus) \|x\|
sign(x)	sign of a number = -1, if x < 0; 1, if x > 0; 0 if x = 0
random(x)	random number between 0 and x
sin(x)	sine
cos(x)	cosine
tan(x)	tangent = sin(x)/cos(x), for each x ≠ kπ, k=1, 2, 3…
csc(x)	cosecant = 1 / sin(x)
sec(x)	secant = 1 / cos(x)
cot(x)	cotangent = cos(x) / sin(x), for each x ≠ π/2 + kπ, k=1, 2, 3…
asin(x)	inverse sine, defined for -1 ≤ x ≤ 1
acos(x)	inverse cosine, defined for -1 ≤ x ≤ 1
atan(x)	inverse tangent
atan2(x; y)	the angle which tangent is y/x
acsc(x)	inverse cosecant = asin(1/x)
asec(x)	inverse secant = acos(1/x)
acot(x)	inverse cotangent = atan(1/x)
sinh(x)	hyperbolic sine = (e^x – e^–x) / 2
cosh(x)	hyperbolic cosine = (e^x + e^–x) / 2
tanh(x)	hyperbolic tangent = (e^x – e^–x) / (e^x + e^–x)
csch(x)	hyperbolic cosecant = 1 / sinh(x)
sech(x)	hyperbolic secant = 1 / cosh(x)
coth(x)	hyperbolic cotangent = 1 / tanh(x) = (e^x + e^–x)/ (e^x – e^–x), for x ≠ 0
asinh(x)	inverse hyperbolic sine = ln(x + √(x² + 1)), for -∞ ≤ x ≤ +∞
acosh(x)	inverse hyperbolic cosine = ln(x + √(x + 1)·√(x – 1)), for x ≥ 1
atanh(x)	inverse hyperbolic tangent = 1/2·ln[(1 + x) / (1 – x)], for -1 < x < 1
csc(x)	inverse hyperbolic cosecant = asinh(1/x)
sec(x)	inverse hyperbolic secant = acosh(1/x)
acoth(x)	inverse hyperbolic cotangent = atanh(1/x) = 1/2·ln[(x + 1) / (x – 1)], for \|x\| > 1
log(x)	decimal logarithm (with base 10), for each x > 0
ln(x)	natural logarithm (with base e ≈ 2.7183), for each x > 0
log_2(x)	binary logarithm (with base 2)
exp(x)	exponential function = e^x
sqr(x) or sqrt(x)	square root (√x), defined for each x ≥ 0
cbrt(x)	cubic root (³√x)
root(x; n)	n-th root (ⁿ√x)
min(x; y; z…)	the smallest of multiple values
max(x; y; z…)	the greatest of multiple values
round(x)	rounds to the nearest integer
floor(x)	rounds to the smaller integer
ceiling(x)	rounds to the greater integer
trunc(x)	rounds to the nearest integer towards zero
re(a + bi)	the real part of a complex number, re(a + bi) = a
im(a + bi)	the imaginary part as a real number, im(a + bi) = b
abs(a + bi)	complex number modulus = sqrt(a`^`2 + b`^`2)
phase(x)	complex number phase (argument) = atan2(a; b)
if(cond; val-if-true; val-if-false)	conditional evaluation
switch( cond1; value1; cond2; value2; …; default)	selective evaluation;
sum(x; y; z…)	sum of multiple values = x + y + z…;
sumsq(x; y; z…)	sum of squares = x² + y² + z²…;
srss(x; y; z…)	square root of sum of squares = sqrt(x² + y² + z²…);
average(x; y; z…)	average of multiple values = (x + y + z…)/n;
product(x; y; z…)	product of multiple values = x·y·z…;
mean(x; y; z…)	geometric mean = n-th root(x·y·z…);
take(n; a; b; c…)	returns the n-th element from the list;
line(x; a; b; c…)	linear interpolation;
spline(x; a; b; c…)	Hermite spline interpolation;

Custom

You can define custom functions of multiple arguments:
f(x; y; z; ...) = expression

Function names are subjected to the same rules as variable names (see above).

Plotting

There are several different plotting commands:
$Plot{y(x) @ x = a : b} – plots the function y(x) within the interval [a; b].
$Plot{y1(x) & y2(x) & ... @ x = a : b} – plots several functions y1(x), y2(x), etc. in a single plot.
$Plot{x(t) | y(t) @ t = a : b} – plots a curve where both x(t) and y(t) are functions of a single parameter t.
$Plot{x1(t) | y1(t) & x2(t) | y2(t) & ... @ t = a : b} –
plots several parametric curves on a single plot.
$Map{f(x; y) @ x = a : b & y = c : d} – plots a function of two variables as a color/grayscale map.

Size of plot area

You can specify the size of the plot area in pixels by defining the PlotWidth and PlotHeight variables, e.g.:

PlotWidth = 400
PlotHeight = 250

The above values are the default ones.

Numerical and iterative procedures

You can use numerical methods for problems that do not have a closed form solution:
$Root{f(x) = const @ x = a : b} – finds the root of the equation f(x) = const within the interval [a; b], using modified Anderson Bjork method.
$Root{f(x) @ x = a : b} – finds the root of the equation f(x) = 0.
$Find{f(x) @ x = a : b} – finds the point where the function crosses the abscissa (it is not required to be a root).
$Inf{f(x) @ x = a : b} – finds the minimum value f_{_inf} of the function f(x), using the golden section search method. The location of minimum on the abscissa is stored in the x_{_inf} variable.
$Sup{f(x) @ x = a : b} – finds the maximum value f_{_sup} of the function f(x), using the golden section search method. The location of maximum on the abscissa is stored in the x_{_sup} variable.
$Area{f(x) @ x = a : b} – finds the definite integral of the function f(x) in the interval [a; b], using the adaptive Gauss-Lobatto rule.
$Integral{f(x) @ x = a : b} – finds the definite integral of the function f(x) in the interval [a; b], using the double exponential Tanh-Sinh quadrature.
$Slope{f(x) @ x = a} – finds the slope of the tangent to f(x) at point x = a.
$Sum{f(k) @ k = a : b} – sums the values of f(x) for all integer values of k between a and b.
$Product{f(k) @ k = a : b} – multiplies the values of f(x) for all integer values of k between a and b.

You can use this command to define your own function for calculation of factorial and binomial coefficients:

F(n) = $Product{k @ k = 1 : n}
C(n; k) = $Product{(i + n - k)/i @ i = 1 : k}

$Repeat{f(k) @ k = a : b} – calculates f(x) repeatedly for all integer values of k between a and b.
$Repeat{x = f(x; k) @ k = a : b} – similar to the above, but sores the result into a variable to be used for the next iteration.

Units of measurement

Calcpad supports the use of physical units in the calculations. Just write the units next to the respective values. You can also specify target units for the result, separated by a vertical bar at the end:

1.23m + 35cm + 12mm|cm

The above expression will evaluate to 159.2 cm. Version 3.0 supports metric, imperial and US units.

Metric units (SI and compatible):

Physical property	Units of measurement
Angles	°, ′, ″, deg, rad, grad, rev
Mass	g (gram), hg, kg, t, kt, Mt, Gt, dg, cg, mg, μg, ng, pg, Da (Dalton), u
Length	m (meter), km, dm, cm, mm, μm, nm, pm, AU (astronomical unit), ly (light year)
Time	s (second), ms, μs, ns, ps, min, h, d
Frequency	Hz (Hertz), kHz, MHz, GHz, THz, mHz, μHz, nHz, pHz, rpm (rotations per minute)
Velocity	kmh (km per hour)
Electric current	A (Ampere), kA, MA, GA, TA, mA, μA, nA, pA
Temperature	°C (degree Celsius), Δ°C (difference of one °C), K (Kelvin)
Amount of substance	mol (mole)
Luminous intensity	cd (candela)
Area	a (are), daa (decare), ha (hectare)
Volume	L (liter), mL, cL, dL, hL
Force	N (Newton), daN, hN, kN, MN, GN, TN, dyn, gf, kgf, tf
Moment	Nm (Newton-meter), kNm
Pressure	Pa (Pascal), daPa, hPa, kPa, MPa, GPa, TPa, dPa, cPa, mPa, μPa, nPa, pPa, bar, mbar, μbar, atm, at, Torr, mmHg;
Energy, work	J (Joule), kJ, MJ, GJ, TJ, mJ, μJ, nJ, pJ, Wh, kWh, MWh, GWh, TWh, cal, kcal, erg, eV, keV, MeV, GeV, TeV, PeV, EeV;
Power	W (Watt), kW, MW, GW, TW, mW, μW, nW, pW, hpM, ks;
Electric charge	C (Coulomb), kC, MC, GC, TC, mC, μC, nC, pC, Ah, mAh
Potential	V (Volt), kV, MV, GV, TV, mV, μV, nV, pV
Capacitance	F (Farad), kF, MF, GF, TF, mF, μF, nF, pF
Resistance	Ω (Ohm), kΩ, MΩ, GΩ, TΩ, mΩ, μΩ, nΩ, pΩ
Conductance	S (Siemens), kS, MS, GS, TS, mS, μS, nS, pS
Magnetic flux	Wb (Weber), kWb, MWb, GWb, TWb, mWb, μWb, nWb, pWb
Magnetic flux density	T (Tesla), kT, MT, GT, TT, mT, μT, nT, pT
Inductance	H (Henry), kH, MH, GH, TH, mH, μH, nH, pH
Luminous flux	lm (lumen)
Illuminance	lx (lux)
Radioactivity	Bq (Becquerel), kBq, MBq, GBq, TBq, mBq, μBq, nBq, pBq, Ci, Rd;
Absorbed dose	Gy (Gray), kGy, MGy, GGy, TGy, mGy, μGy, nGy, pGy;
Equivalent dose	Sv (Sievert), kSv, MSv, GSv, TSv, mSv, μSv, nSv, pSv;
Catalytic activity	kat (katal)

Imperial/USCS units:

Physical property	Units of measurement
Mass	gr (grain), dr (drachm), oz (ounce), lb (pound), kip (kilopound), st (stone), qr (quarter), cwt (hundredweight), cwt_{_UK}, cwt_{_US}, ton, ton_{_UK}, ton_{_US}, slug
Length	th (thou), in (inch), ft (foot), yd (yard), ch (chain), fur (furlong), mi (mile), ftm (fathom), cable, nmi (nautical mile), li (link), rod, pole, perch, lea (league)
Velocity	mph (miles per hour)
Temperature	°F (degree Fahrenheit), Δ°F (difference of one °F), R (Rankine)
Area	rood, ac (acre)
Volume (fluid)	fl_{_oz} (fluid ounce), gi (gill), pt (pint), qt (quart), gal (gallon), bbl (barrel), bu (bushel, dry) fl_{_oz_UK}, gi_{_UK}, pt_{_UK}, qt_{_UK}, gal_{_UK}, bbl_{_UK}, bu_{_UK} fl_{_oz_US}, gi_{_US,} pt_{_US}, qt_{_US}, gal_{_US}, bbl_{_US}, bu_{_US}
Force	ozf (ounce-force), lbf (pound-force), kipf (kilopound-force), tonf (ton-force), pdl (poundal)
Pressure	osi (ounce per sq. inch), osf (ounce per sq. foot), psi, psf, ksi, ksf, tsi, tsf, inHg

Comments

Everything inside a Calcpad script is considered to be math expressions unless it is enclosed by quotes. Then it is treated as comments. You can use them to add contents to your calculation notes, such as titles, text, images, tables etc.

Comments can be enclosed in double (“) or single (‘) quotes. Double quotes are used for “titles” and single quotes for ‘normal text’. You can have several expressions in a single line, separated by comments. The closing quote is not required if there is nothing else in the line.

Comments can contain plain text as well as Html, CSS, JS (jQuery), SVG, etc. for providing rich formatting and user experience for your calculation notes. For example, you can use Html to fold part of the content:

'<div class="fold">
"This is a folded content
'This line is hidden until you unfold it
'</div>

Program flow control

You can split the flow of your calculation notes depending on certain intermediate values. It will not only use different formulas for calculations, but it can also display different text and images in your report.
You can use the following patterns:

Conditions

#If condition1
    'code if condition1 is true
#Else If condition2
    'code if condition2 is true
#Else If condition3
    ...
#Else
    'code if non of the conditions is true
#end if

Shorter forms are also possible:

#If condition
    'code if condition is true
#Else
    'code if conditions is false
#end if

or:

#If condition
    'code if condition is true
#end if

Loops

Simple:

#Repeat n
    'Put some code here
#Loop

Here n is the number of iterations and not the counter. If you need a counter, you have to define it as follows:

i = 0
#Repeat n
    i = i + 1
    'Put some code here
#Loop

With conditional break or continue:

#Repeat
   'Put some code here
    #If condition
        #Break or #Continue
    #End if
    'Some more code
#Loop

Modules and macros/string variables

Modules:

#Include filename – incudes external file/module
#Local – starts a local section in a module (not to be included)
#Global – starts a global section in a module (to be included)

Inline string variable:

#def variable_name$ = content

Multiline string variable:

#def variable_name$
    content line 1
    content line 2
    ...
#end def

Inline macro:

#def macro_name$(param1$; param2$; ...) = content

Multiline macro:

#def macro_name$(param1$; param2$; ...)
    content line 1
    content line 2
    ...
#end def

Output control

You can control the visibility of your code in the output using the following keywords:
#Hide – hide the contents after the current line;
#Pre – show the contents in input form mode only (see “Input forms” bellow) and hide it otherwise;
#Post – show the contents in calculated mode only and hide it in input form mode;
#Show – always show the contents (revoke all other commands);

You can also modify the rendering style of the calculations as follows:
#Val – shows only the result as a single value;
#Equ – shows the complete equation and the result;
#Noc – shows only the equation without the result (no-calculations).

The next two keywords allows you to select the default units for angles inside your calculation notes:
#deg – assumes that angles are in degrees: sin(90) = 1;
#rad – assumes that angles are in radians: sin(π/2) = 1;
#gra – assumes that angles are in grades: sin(100) = 1;

Rounding options:
#round n – rounds the output to n digits after the decimal point;

Breakpoints for step-by-step execution:
#pause – calculates to the current line and waits for the user to resume manually;
#input – renders an input form to the current line and waits for user input.

These settings affect all calculations after the current line.