Hurmet Reference Manual

Introduction

Hurmet is a rich-text editor that gives you the ability to create high quality calculation documents using standard math notation.

Hurmet calculations are much easier to read and check than spreadsheet calculations. Hurmet does not hide the active expressions and intermediate values of a calculation. They’re all open for review in the displayed document.

You are welcome to use the Hurmet.org web page under terms of the MIT License. The source code is available in Hurmet’s GitHub repository.

Editor Basics

Hurmet provides rich-text editing capabilities. You can apply styles to a document range by selecting text, then clicking one of the menu bar buttons:

≡	Navigate…
File▾	Open…, Save…, Import/Export to Markdown, Take a snapshot, Show diff, Set Page Size, Print
Doc▾	Set Decimal, Font size, Draft Mode, Print header, Delete all comments
	Recalculate all
	Undo, Redo
B  I   X2 X2   U	Character styles: Bold, Italic, Code, Subscript, Superscript, Strikethrough, Underline
— ToC	Insert: Link…, Horizontal rule, Uploaded image…, Link to image…, Footnote, Table of Contents…, Calculation…, TeX…, Macro expansion, Comment…
¶ H1 H2 Centered Indented Boxed Note Tip Important Warning ⬚	Block styles: Plain paragraph, Code block, Headings, List, Ordered list, Centered Indented Boxed Note Important Warning Select Parent
Tbl Style	Table: Insert table, Insert row, Insert column, Delete table, Delete row, Delete column, Toggle cell merge, Align left, Align center, Align  right, Set table style
Q	Information, Quick Reference

Save/Open

You can save your work using Ctrl-S or the save command in the File menu. Then reopen it using the File | Open… menu choice. In Chrome and Edge, the save button is smart enough to re-save your work to the same file you opened earlier. In Firefox and Safari, the save button always works like a Save As… button.

Tracking Changes

The File▾ menu contains commands that enable you to track changes:

• Take a snapshot… will store a snapshot of the current document (not including embedded images)

• Show diff… will display the differences between a chosen snapshot and the current document.

• Delete all snapshots…, for when you no longer need to track changes.

Snapshots and diffs are displayed in Markdown format.

Print Header

You can create a print header in any document by clicking the File | Print Header menu choice. Later, when you click the File | Print… menu choice, the header will be printed at the top of every page (except the cover page). The header is a table and it should remain a table. Otherwise, edit it any way you want.

If you write $PAGE into a print header, Hurmet will print page numbers at that location.

Macro Expansion

To expand a macro, (1) write the macro name in your document, put the selection point after the name, and then (2) hit the button or type Alt+E. Hurmet will replace the macro name with the macro expansion.

To learn how to write macros or how to import macros, see the macros section, below.

Comments

The button enables you to write a comment into the document.

A command in the “Docs” menu will delete all comments in the document.

Table of Contents

The ToC button creates a Table of Contents at the selection point. The table will be built from Headings in your document. In the ToC dialog box, you can choose which heading levels to include.

Markdown

Hurmet documents are saved in Markdown, a lightweight, easy-to-read markup format. Hurmet's version of Markdown is extended to enable calculations, complex tables, and more.

Click for more…

Paragraphs are preceded by a blank line.
A newline is indicated by a backslash, \, at the end of a line.

Type…	To get…
_Italic_	Italic
**Bold**	Bold
**_Bold Italic_**	Bold Italic
~subscript~	subscript
~~strikethrough~~	strikethrough
`inline code`	inline code
¢` calcu = la/tion `	$\mathrm{c}\mathrm{a}\mathrm{l}\mathrm{c}\mathrm{u}={\displaystyle \frac{\mathrm{l}\mathrm{a}}{\mathrm{t}\mathrm{i}\mathrm{o}\mathrm{n}}}$
$\TeX$	$\text{T}\text{E}\text{X}$
# Heading 1	Heading 1
## Heading 2	Heading 2
[Link][link id]	Link
![alt][id]
!![image and caption][id]
[id]: filepath	path to image or link
> Blockquote	| Blockquote
* List * List * List	List List List
1. One 2. Two 3. Three	One Two Three
``` #code block print "Hi!" ```	# code block print "Hi!"
---------
::: boxed Block elements. The attribute can be `indented`, `centered`, `boxed`, or `header`. :::	Block elements. The attribute can be indented, centered, boxed, or header.
> [!NOTE] > Alerts. The attribute can be > `NOTE`, `TIP`, `IMPORTANT`, or > `WARNING`.	Alerts. The attribute can be NOTE, TIP, IMPORTANT, or WARNING.

Pipe Tables

| Head 1  |  Head 2  | Head 3  |
|:--------|:--------:|---------|
| datum 1 | datum 2  | datum 3 |
| datum 4 | datum 5  | datum 6 |

Grid tables

+-----------+-------------------------+
| Heading 1 |  Merged Heading         |
+:=========:+=========================+
| datum 1   | merged cell             |
+-----------+---------------+---------+
| merged\   | datum 3       | datum 4 |
| cell      +---------------+---------|
|           | datum 5       | datum 6 |
+-----------+---------------+---------+
| datum 7   | * cells can   | datum 8 |
|           | * contain     |         | 
|           | * block       |         |
|           | * elements    |         |
+-----------+---------------+---------+

TeX

Besides its calculation cells, Hurmet also has cells that emulate the math mode of $\text{T}\text{E}\text{X}$ (pronounced tech). These cells display, but do not calculate, math. You can create a TeX cell by clicking the button. Type Enter to save the cell.

To create a cell in TeX display mode, first change the paragraph format to center-justified, then create the cell.

For more information about TeX and LaTeX, good places to start are the Wikibooks pages for writing math and advanced math; and the Temml home page and supported-functions page.

Hurmet calculation cells use a different syntax than TeX. In calculation cells, the syntax is more akin to a programming language, yet it renders like mathematics.

And now, on to the main event, Hurmet’s calculations.

Calculation Tutorial

Create a cell

Hurmet calculation cells display math and perform numeric calculations. To create a calculation cell in Hurmet.org, select a spot in the document, then click the button or type Alt c.

While in a cell,
      Enter will close and update the cell.
       Shift-Enter will create a newline inside the cell.
       Esc will close the cell without updating it.
      Clicking elsewhere will also close the cell.

Statements

Inside a calculation cell, we can write an statement and get a numeric result. In the demonstration box to the right, try replacing the text with 2 + 2 = ?. Hurmet will render the math and write the result where you place the ? mark.

Numbers

Numbers can be written as integers (33), decimals (2.45), or mixed fractions (3 ⁷⁄₈). There is a more detailed description below.

Arithmetic

The symbols: + - × / ^ √ are some of Hurmet’s arithmetic operators. Try an equation such as 2 × 4 + 3^2/7 = ?. Play with changes to the values and operators to see how they work. See here for more operators.

Multiplication

Hurmet accepts several multiplication syntaxes. If $a=7.1$, then the following all give the same result:

$2\times 7.1$
$2*7.1$
$2\cdot 7.1$
$2\circ 7.1$
$2a$
$(2)(7.1)$

To obtain the character $\times$, type xx and hit the space bar. Auto-correct will give you an $\times$.

A space between variables acts as a multiplication operator.

Roots

Type sqrt and hit the spacebar to auto-correct into √.
root 3 and root 4 will also auto-correct into roots.

Function

Hurmet treats a word as a function name if it is placed directly before an open parenthesis. Example: $\sin \left(\frac{\pi }{6}\right)=0.5$. Hurmet has many built-in functions.

Variables

$L=3.1$   ← That kind of statement will assign a value to a variable. Subsequent cells can then use the variable.
Example: 2 L = ? will result in: $2L=(2)(3.1)=6.2$

A variable name must be a valid identifier.

An assignment statement can also contain a calculation expression. Example:
b = 2 L = ? will result in $b=2L=(2)(3.1)=6.2$

Subscripts

An underscore signals the beginning of a subscript. Examples: x_left and y_(i+1) result in $x{}_{\text{left}}$ and $y_{i+1}$.

Exponents

A carat signals the beginning of an exponent. Examples: x^23 and y^(i+1) result in $x^{23}$ and $y^{i+1}$

Greek letters

To write a Greek letter, write the name of the letter and hit the space bar. So, alpha ↦ α and beta ↦ β. More detail here.

Accents and Primes

To write an accent above a single-letter variable, write the accent name and hit the space bar for an auto-correction. Examples:

y bar ↦ $\bar{y}$
θ hat ↦ $\hat{\theta }$
P vec ↦ $\overrightarrow{P}$
x dot ↦ $\dot{x}$

More detail here.

To write a prime, type two apostrophes (aka single quotation marks) and hit the space bar. So, f'' will result in $f^{\prime }$

Units

After a number, write a Hurmet unit between two single quotation marks, like this: 5 'meters'. Or, prepend a currency symbol to a number, e.g. $30.

Unit-Aware Calcs

Hurmet can automatically handle unit conversions of quantities. To call for a unit-aware calculations, write ?? instead of ? where you want the result to appear. Example:
2 × 3.1 'm' = ?? ft results in $2\times (3.1\text{m})=13.1\mathrm{f}\mathrm{t}$.

This is covered in more detail below.

Result Rounding

To specify how results are to be rounded, use the format statement. Examples:
format = "f2"   fixed to 2 places after decimal.
format = "r3"   rounded to 3 significant digits.
format = "h3"   like "r3", but doesn’t round integers.
More details below.

Display Mode

Display mode centers a calculation cell and enlarges summation symbols and integration symbols. To get display mode, first set a paragraph to centered, then create the cell.

Quick Reference

Markup

Calculation cells also support many of the math-mode TeX functions supported by Temml. Put function arguments between parentheses, not braces, as in \cancel(5) instead of \cancel{5}.

TeX functions are provided for use in displaying math. Not all of them are valid in calculations.

A few color functions are valid in calculations, but only if their argument is a string. These are: \blue, \gray, \green, \orange, \pink, \purple, and \red.

Auto-correct

Auto-correct kicks in when you type a space inside a math zone.

The font corrections, e.g., bb … work on any letter from A to Z or a to z. You can also make one those letters bold by typing it and then typing Ctrl+B.

-->, <--, and <--> will auto correct into extensible arrows, as in: $A\stackrel{\stackrel{}{\text{note}}}{\to }B$.

<space> auto-corrects to ˽ in the text editor, which renders as a space.

Display Selectors

   ?

  ??

   %

  %%

   @

 @@

   !

  !!

Accessors

Data Type and Example	Accessor	Returns
string s = "abcde"	s[2] s[2:4] s[3:end]	b bce cde
Vector 𝐕 = $\left[\begin{array}{c}1\\ 2\\ 3\\ 4\\ 5\end{array}\right]$	𝐕[2] 𝐕[2:4] 𝐕[3:end]	2 $\left[\begin{array}{c}2\\ 3\\ 4\end{array}\right]$ $\left[\begin{array}{c}3\\ 4\\ 5\end{array}\right]$
Matrix 𝐌 = $\left(\begin{array}{ccc}1& 2& 3\\ 4& 5& 6\\ 7& 8& 9\end{array}\right)$	𝐌[2, 3] 𝐌[3,:] 𝐌[2:3, 1:2]	6 $\left[\begin{array}{ccc}7& 8& 9\end{array}\right]$ $\left(\begin{array}{cc}4& 5\\ 7& 8\end{array}\right)$
Data Frame	DF.B DF["B"] DF.area DF.B.area DF["B"].area DF["B", "area"] DF.w[1]	An entire row An entire row Column vector 22 22 22 4

Dot notation can be used only if the property name is a valid identifier.

Calculation Forms

Hurmet calculation cells don’t just display math; they compute numerical results.

It’s quite simple to assign a value to a variable:

Form	Examples
	x = 5
	L = 3.1 'm'
	w = 100 'lbf/ft'
	name = "James"

To calulate an expression that contains a variable, a function, or an operator; write a ? or % or @ to indicate where the result should appear. Here are some examples:

The statement form is more precisely defined as:

At the beginning of the statement, you can write an optional variable name. The result of the calculation will be assigned to that variable. Expressions later in the document can call the variable. Variable names must qualify as valid identifiers. They are case-sensitive and bold-sensitive. A search for variable E will not find e. A search for M will not find M.

You can define a unit for the result with a leading currency symbol or a trailing unit name, but not both in the same statement.

You can also slip in a ; character just before the final = sign in a statement. That will create a multiple line statement, with aligned = signs.

Display Selector

Near the end of the statement is the display selector, i.e., ?, ??, etc. It determines how much of the calculation is displayed.

   ?

  ??

   %

  %%

   @

 @@

   !

  !!

For an engineer like me, the most common display selector is ??. I almost always want to see the entire calculation. Seeing the expression and the plugged-in values helps me to avoid the kind of unseen errors that creep into spreadsheet calculations. And it makes the calculation reviewable by a second set of eyes.

A doubled selector will prompt a unit-aware calculation. After you try them, you may wonder how you ever did without them.

I use the ! selector mostly when I am assigning a chunk of data to a variable.

I try to resist the temptation to overuse the % selector. When I review work done by another engineer, I can do without the blue echo if variable values are assigned directly above the equation where they are used. Otherwise I get grumpy. You don’t want a grumpy reviewer.

One last variation is possible when assigning values from a single-row data frame. You can assign such values to more than one variable at a time, like this:

A, I, w_self = beam["A", "Ix", "weight"] = !!

Identifiers

Variable names and function names must be written in the form of a valid identifier.

• Identifiers may be multiple characters long.

• The first character must be a letter from the Latin or Greek alphabet. It may be bold or capitalized calligraphic Latin, or ℏ, or ℓ.

• Subsequent characters may be letters or numerals (0123456789).

• An under-score within an identifier is allowed and will be interpreted to mean the start of a subscript.

• If an identifier has only one letter, then an accent character may be written after it. Hurmet will render the accent above the letter, as in $\hat{\theta }$.

• Primes may be appended to the very end, as in: $f{}_{\text{c}}^{\prime }$.

• The following keywords may not be used as variable names: π, ℏ, pi, true, false, root, if, else, elseif, otherwise, end, and, or, in, to.

  

The names of those accents are:

Hurmet’s auto-correct can help create identifiers.

Hurmet will render single Latin letter variable names in italic. Function names and multi-letter variable names are rendered in upright font. As a convention, I personally use bold letters for variables that contain vectors or matrices.

Data Types

Boolean

true or false

String

A string literal is a string of text characters enclosed by a pair of straight double quotation marks. The string may include any Unicode character except a straight double quotation mark, a newline, or a carriage return.

"This is a string."

You can call a subset of any string with an index or range in brackets. Hurmet indices are one-based. Examples:

a = "abcdefg"
a[2]      # returns "b"
a[2:4]    # returns "bcd"
a[5:end]  # returns "efg"

Math String

Strings will be rendered as math if they are delimited with single backticks instead of double quotes. So somthing like `M_n` will return as $M{}_{\text{n}}$. This is useful mostly when a calculation checks a condition and reports whether some computed variable can be accepted.

Number

Enter as integers (33), decimals (2.45), percentages (3.2%), scientific notation (3.1e4), mixed fractions (3 ⁷⁄₈) or hexadecimal (0x2A).

Notice that a number literal must begin and end with a numeral, not a decimal symbol. Hurmet will not recognize 5. as a number.

Hurmet’s default decimal symbol is a dot. You can choose instead to enter numbers with a decimal comma via a drop-down menu in the Doc menu. Numbers are never entered with a thousands separator, but they can be displayed with one.

Hurmet always saves a decimal symbol as a dot. It’s only the display that changes.

While calculations are underway, Hurmet holds every number in memory in rational number format. The numerator and denominator are each integers of arbitrary length. So Hurmet can work precisely with numbers like 0.1 and 0¹⁄₃. Trignonometry and roots are done in double-precision floating point, good to about 15 significant digits.

Complex Number

One can write a complex number in two forms:

• $a\pm jb$    The letter j is identical to $\sqrt{\text{-}1}$ by Hurmet definition. Write a space after the j, as in 2 - j 3.

• $r\angle \theta$    The characters /_ will auto-correct into ∠ and $\theta$ is in radians.

Also, the character ° is now a unit name. So one can also write a polar notation as $r\angle \theta °$ and the phase angle will be unit-aware. The characters ooo will auto-correct into °

Examples:

$z{}_{\text{1}}=2+j3$

$z{}_{\text{2}}=4\angle 30°$

$z=z{}_{\text{1}}+z{}_{\text{2}}=(2+j3)+(4\angle 30°)=5.46+j5$

Unit

A Humet unit can be applied to a numeric value. There are three ways to write a Hurmet unit.

1. A unit name between apostrophes, aka single straight quotation marks, written after a numeric value.

2. A unit symbol written after a numeric value.

3. A currency symbol written before a non-negative number.

Input	Renders as
4.2 'meters'	$4.2\text{meters}$
30°	$30°$
$25.10	$\$25.10$
10 'N·m/s'	$10\text{N}\cdot \text{m/s}$
[2.1; 15.3] 'feet'	$\left[\begin{array}{c}2.1\\ 15.3\end{array}\right]\text{feet}$

Hurmet treats the number and the unit together as a single quantity. Quantities are useful in unit-aware calculations which do automatic unit conversion and also check for unit compatibility.

Hurmet has many built-in unit definitions. You can write any one of them into a quantity. SI (metric) prefixes are valid on the appropriate unit names.

You can also create compound units on the fly. That is, you can raise any unit to a power, and these powers-of-units can be multiplied (or divided) together into products. Example:

Input	Renders as
4 'kW.hr/m2'	$4\text{kW}\cdot {\text{hr/m}}^2$

Note that within the unit literal, it is not necessary to write ^ to indicate a numeric exponent. Also, a dot or a hyphen within a compound unit name will be rendered as a half-high dot.

Only one division solidus, /, may be written into a compound unit.

Matrix

A Hurmet matrix is a one or two dimensional arrangement of matrix elements. A Hurmet matrix element can be a number, a string, true, false, or an exprression that resolves to one of those simple types.s

A matrix literal is written between delimiters, either ( ) or [ ] or {: }. Matrix elements are horizontally separated by tabs or commas. Matrix rows are separated by semi-colons. So this: (1, 0; 0, 1) renders as $\left(\begin{array}{cc}1& 0\\ 0& 1\end{array}\right)$.

A Hurmet vector is a one dimensional array. Write a vector literal with values separated by commas or semi-colons, but not both.

Input	Renders as
[2.1, -15.3]	$\left[\begin{array}{cc}2.1& \text{-}15.3\end{array}\right]$
[4; 5]	$\left[\begin{array}{c}4\\ 5\end{array}\right]$
[]	$[]$

Another way to create a Hurmet column vector is to write a range of numbers between brackets; the form is [start:step:end...]. A Hurmet calculation of that form will return a column vector with every number in the range. The step size is optional (default = 1). Examples:

Input	Result
[2:5...] = ?	$[2:5\dots ]=\left[\begin{array}{c}2\\ 3\\ 4\\ 5\end{array}\right]$
[1:2:5...] = ?	$[1:2:5\dots ]=\left[\begin{array}{c}1\\ 3\\ 5\end{array}\right]$

You can call individual elements with index integers between brackets, as in 𝐕[5] or 𝐌[1, 3]. You can use a variable name for the index if the variable returns an integer. Hurmet indexes are one-based.

You can access a sub-matrix using the range operator, “:”, as in 𝐕[2:5] or 𝐕[2:end]. Entire rows or columns can be called, as in 𝐌[2,:] or 𝐌[:,1].

Matrix Operations

All the usual math operators can be applied to a numeric matrix. The operators mostly work in an element-wise fashion. If you add a scalar to a matrix, or pass a matrix to most functions, Hurmet will do an element-by-element calculation and return a matrix, as in:

$𝐡=\left[\begin{array}{c}5\\ 10\\ 15\end{array}\right]$

$𝐱=2𝐡+1=2\left[\begin{array}{c}5\\ 10\\ 15\end{array}\right]+1=\left[\begin{array}{c}11\\ 21\\ 31\end{array}\right]$

Spreadsheet calculations can often be replaced by calulations using vectors, as above. When you really need to get things right, it’s great to be able to see the expression and all the plugged-in values.

Multiplication of two matrices is different than other operations. Mathematicians have several ways to multiply matrices. In Hurmet, you choose the type of multiplication by your choice of multiplication operator:

$𝐀\circ 𝐁$ ↦ element-wise product, $(𝐀\circ 𝐁{)}_{\mathrm{i}\mathrm{j}}=\mathrm{𝐀}{}_{\text{ij}}\times \mathrm{𝐁}{}_{\text{ij}}$

$𝐀𝐁$ or $𝐀*𝐁$ ↦ matrix product, $(𝐀𝐁{)}_{\mathrm{i}\mathrm{j}}={\displaystyle \sum _{k=1}^m\mathrm{𝐀}{}_{\text{i}}\mathrm{𝐁}{}_{\text{kj}}}$

$𝐀\times 𝐁$ ↦ cross product of a pair of three-vectors     = $|𝐀||𝐁|\sin (\theta )𝐧$

$𝐀\cdot 𝐁$ ↦ dot product = ${\displaystyle \sum _{i=1}^n(\mathrm{𝐀}{}_{\text{i}}\mathrm{𝐁}{}_{\text{i}})}$

Here are more of Hurmet’s matrix operations:

${𝐀}^T$ ↦ a transposed matrix.

${𝐀}^{\text{-}1}$ ↦ an inverted matrix, if $𝐀$ is square.

$|𝐀|$ ↦ $\{\begin{array}{cc}\mathrm{d}\mathrm{e}\mathrm{t}\mathrm{e}\mathrm{r}\mathrm{m}\mathrm{i}\mathrm{n}\mathrm{a}\mathrm{n}\mathrm{t}& \mathrm{i}\mathrm{f}\text{𝐀 is square}\\ \mathrm{m}\mathrm{a}\mathrm{g}\mathrm{n}\mathrm{i}\mathrm{t}\mathrm{u}\mathrm{d}\mathrm{e}& \mathrm{o}\mathrm{t}\mathrm{h}\mathrm{e}\mathrm{r}\mathrm{w}\mathrm{i}\mathrm{s}\mathrm{e}\end{array}$

$\mathrm{abs}(𝐀)$ ↦ element-wise absolute values

$\text{‖}𝐀\text{‖}$ ↦ $\{\begin{array}{cc}\sqrt{x{{}_{\text{1}}}^2+\cdots +x{{}_{\text{n}}}^2}& \mathrm{i}\mathrm{f}\text{𝐀 is a vector}\\ \sqrt{{\displaystyle \sum _i{\displaystyle \sum _{j}A{{}_{\text{ij}}}^2}}}& \mathrm{i}\mathrm{f}\text{𝐀 is a matrix}\end{array}$

$𝐀\&𝐁$ or $\mathrm{hcat}(𝐀,𝐁)$ ↦ concatenate matrices 𝐀 and 𝐁 horizontally

$\mathrm{vcat}(𝐀,𝐁)$ ↦ concatenate 𝐀 and 𝐁 vertically

$𝐀\&e$ ↦ append an element to any vector

Functions will mostly work element-wise on an matrix. Exception: functions min() and max() will find the minimum or maximum of the elements in the matrix.

If you want to write a semi-colon inside parentheses and not create a matrix, use \;.

Data Frame

A data frame is a two dimensional data structure that can be accessed with row names and column names or by row indices and column indices.

Each datum can be a number, a string, true, or false. A missing item will be taken to be undefined. All data in a column must be of the same data type. A column of numbers can be assigned a unit of measure.

Data frame literals are written between double backtick delimiters. The text between the backticks must be written in TSV format. (tab-separated values)

Numbers must use a dot decimal. The second row may contain units of measure. Tabs and newlines are disallowed in data. Quotation marks, ", have no special significance.

Here’s an example of TSV input:

rebar = ``#size	diameter	area
 	in     	in²
#3	0.375  	0.11
#4	0.5    	0.2
#5	0.625  	0.31
#6	0.75   	0.44``

… which renders as:

$\mathrm{r}\mathrm{e}\mathrm{b}\mathrm{a}\mathrm{r}=\begin{array}{lll}\text{size}& \text{diameter}& \text{area}\\ & \text{in}& {\text{in}}^2\\ \text{\#3}& 0.375& 0.11\\ \text{\#4}& 0.5\phantom{00}& 0.2\phantom{0}\\ \text{\#5}& 0.625& 0.31\\ \text{\#6}& 0.75\phantom{0}& 0.44\end{array}$

Hurmet will use the first column as keys to the rest of each row if the content of the top left cell begins with a hash tag, #.

A dataframe literal can also show totals on the bottom line, via the sumAbove() function. So this input:

roof = ``#Item             	weight
                           	psf
2 layers asphalt shingles  	8.0
1/2 inch plywood           	1.5
insulation, R19 fiberglass 	0.6
trusses at 16 inch o.c.    	2.5
5/8 inch gypsum board      	2.5
lights, HVAC, miscellaneous	1.5
total                      	sumAbove()``

will render like this:
$\mathrm{r}\mathrm{o}\mathrm{o}\mathrm{f}=\begin{array}{ll}\text{Item}& \text{weight}\\ & \text{psf}\\ \text{2 layers asphalt shingles}& 8.0\\ \text{1/2 inch plywood}& 1.5\\ \text{insulation, R19 fiberglass}& 0.6\\ \text{trusses at 16 inch o.c.}& 2.5\\ \text{5/8 inch gypsum board}& 2.5\\ \text{lights, HVAC, miscellaneous}& 1.5\\ \text{total}& 16.6\end{array}$

Data frames can be quite large, so Hurmet has a fetch(url) function to load data from a remote TSV file into a data frame. Since Hurmet runs in a browser, the url must begin with http: or https:

A fetch example:

wideFlanges = fetch("https://hurmet.org/example.tsv") = !

That example loads in this data:

$\begin{array}{llllllll}\text{name}& \text{weight}& A& d& \text{bf}& \text{tw}& \text{Ix}& \text{Sx}\\ & \text{lbf/ft}& {\text{in}}^2& \text{in}& \text{in}& \text{in}& {\text{in}}^4& {\text{in}}^3\\ \text{W14X90}& 90& 26.5\phantom{0}& 14\phantom{.00}& 14.5\phantom{0}& 0.44\phantom{0}& 999\phantom{.0}& 143\phantom{.00}\\ \text{W12X65}& 65& 19.1\phantom{0}& 12.1\phantom{0}& 12\phantom{.00}& 0.39\phantom{0}& 533\phantom{.0}& 87.9\phantom{0}\\ \text{W10X49}& 49& 14.4\phantom{0}& 10\phantom{.00}& 10\phantom{.00}& 0.34\phantom{0}& 272\phantom{.0}& 54.6\phantom{0}\\ \text{W8X31}& 31& 9.13& 8\phantom{.00}& 8\phantom{.00}& 0.285& 110\phantom{.0}& 27.5\phantom{0}\\ \text{W8X18}& 18& 5.26& 8.14& 5.25& 0.23\phantom{0}& 61.9& 15.2\phantom{0}\\ \text{W6X15}& 15& 4.43& 5.99& 5.99& 0.23\phantom{0}& 29.1& 9.72\\ \text{W4X13}& 13& 3.83& 4.16& 4.06& 0.28\phantom{0}& 11.3& 5.46\end{array}$

As data frames go, that example is still pretty small. When I assign a data frame to a variable, I usually suppress its display by using the ! display selector.

I use a data frame most commonly by calling a row from it, like this:

beam = wideFlanges.W10X49 = !! or
beam = wideFlanges["W10X49"] = !!

That returns a single-row data frame. Then I can call individual properties, like this:

A = beam.A = ?? in2 or
A = beam["A"] = ?? in2 or
A = wideFlanges.W10X49.A = ?? in2

Hurmet will return a
$\{\begin{array}{cc}\text{simple type}& \mathrm{i}\mathrm{f}\text{you call a single cell, as in df[1, 2]}\\ \text{column vector}& \mathrm{i}\mathrm{f}\text{you call a column, as in df[,2]}\\ \text{data frame}& \mathrm{o}\mathrm{t}\mathrm{h}\mathrm{e}\mathrm{r}\mathrm{w}\mathrm{i}\mathrm{s}\mathrm{e}\end{array}$

Dot notation, as in wideFlanges.W10X49, can be used only if the property name is a valid identifier.

Here are calls that can return multiple values:
    A, S_x = wideFlanges.W8X31["A", "Sx"] = !!, or
    A, S_x = wideFlanges["W8X31"]["A", "Sx"] = !! Multiple returns must use the !! display selector, for now.

If the data frame has only one row of data, a single accessor will call a datum.
Say the data frame is    $\mathrm{a}\mathrm{B}\mathrm{a}\mathrm{r}=\begin{array}{lcc}\text{size}& \text{diameter}& \text{area}\\ & \text{in}& {\text{in}}^2\\ \text{\#4}& 0.5& 0.2\end{array}$
Then one can call $A=\mathrm{a}\mathrm{B}\mathrm{a}\mathrm{r}.\text{area}=0.2{\text{in}}^2$

Numeric cata frames can be multiplied by a unit-less scalar. No other math operations are supported for data frames.

For structural engineers, I’ve put some useful data frames on GitHub. There are links below.

Map

A Hurmet map is unit-less data frame in which every value is the same data type, either boolean, string, or number. Maps can be the numeric part of a quantity.

$w=\begin{array}{ccc}\text{dead}& \text{live}& \text{snow}\\ 30& 70& 40\end{array}\text{lbf/ft}$

You can do arithmetic on maps and run them through functions. The operation will be done on each value in the map. For instance, a beam calculation can break the loads down into dead load, live load, snow load, etc.:

$M=\frac{1}{8}w{L}^2=$ $\begin{array}{ccc}\text{dead}& \text{live}& \text{snow}\\ 0.375& 0.875& 0.5\end{array}\text{k}\cdot \text{ft}$

Or, you could do your calculations in matrices and then annotate the matrix by converting it to a map:

$P=\left(\begin{array}{ccc}10& 21.2& 15\\ 11& 25& 14\end{array}\right)\text{kips}$

$P{}_{\text{a}}=\mathrm{matrix2table}(P,\left[\begin{array}{ccc}\text{D}& \text{L}& \text{S}\end{array}\right],\left[\begin{array}{cc}\text{Col A}& \text{Col B}\end{array}\right])=\begin{array}{lccc}& D& L& S\\ \text{Col A}& 10& 21.1& 15\\ \text{Col B}& 11& 25& 14\end{array}\text{kips}$

String Interpolation

Hurmet can do string interpolation, but only inside a data frame or a map, not inside other strings. So data frames can update automatically with values from variables defined elsewhere.

Use ${ before a variable name and } after. Hurmet will write the variable value into that spot in the data. The value will not be unit-aware. Here’s an example.

w_dead = 25 lbf/ft
w = ``dead	live	snow
${w_dead}	30	40`` 'lbf/ft' = %

Note that you must do a calculation. It’s not reading a literal value.

Expressions

Hurmet calculations are meant to be recognizeable to anyone familiar with standard math notation. That is a broad statement. Here are many nuances:

Constants

π or pi

If you write $\pi$ into an expression, Hurmet uses a value of 3.1415926535897932384626433832795028841971693993751.

e

Hurmet will treat $e$ just like any other variable most of the time. But if $e$ is the base of an exponent, for example: $e^x$, then Hurmet will take $e$ to mean 2.7182818284590452353602874713527.

im

$j$ = $\sqrt{\text{-}1}$. This value can be overwritten by a Hurmet assignment.

ℏ

For ℏ, Hurmet uses a value of 1.054571817 × 10⁻³⁴ J·s.

Operators

Functions

Hurmet treats an identifier as a function name if it is placed directly before an open parenthesis. So a term like $\sinh (x)$ is a function.

Functions can return multiple values if the return statement is written in the form: return a, b, c, …, z

Transcendental functions such as trigonometry or logarithms are done to 15 digits precision.

Hurmet’s built-in functions are described below. Unless noted otherwise, they can operate on any real or complex number or any matrix containing real numbers.

abs(z)

Absolute value of a real number. Magnitude of a complex number.

accumulate(𝐕)

Takes a vector, 𝐕, and returns a new vector whose elements are each the sum of the preceding elements in 𝐕.
Example: $\mathrm{accumulate}\left(\left[\begin{array}{ccc}2& 4& 1\end{array}\right]\right)=\left[\begin{array}{ccc}2& 6& 7\end{array}\right]$

acos(z), asin(z), atan(z), asec(z), acsc(z), acot(z)

Inverse trigonometry functions. One can also call an inverse trigonometry function with a superscript, as in ${\cos }^{\text{-}1}x$.

atan(x, y)

When atan is called with two arguments, it returns an angle in the proper quadrant. Given a point defined by real coordinates x and y, atan returns the angle between that point and the positive x-axis of a plane. Real numbers only.

angle(z)

Phase angle of a complex number.

ceil(x)

Ceiling. Always rounds up. Real numbers only.

Char(n)

Takes an integer as a argument, treats it as a Unicode code point, and returns the corresponding string character.
Char(34) returns a double quotation mark.

conj(z)

Complex conjugate of a complex number.

cos(𝜃), sin(𝜃), tan(𝜃), sec(𝜃), csc(𝜃), cot(𝜃)

Trigonometry functions.

The trig functions listed above will assume that a real argument is in radians unless you tell it otherwise. You can tell it otherwise by just writing in a unit, as in: tan(45°) and running a unit-aware calculation.

Complex numbers are also valid arguments.

A positive integer written as a superscript after a trig function name will return the function result raised to a power.
So that: ${\sin }^2\theta =(\sin \theta {)}^2$.

A superscript ^-1 indicates an inverse function. In other words, ${\cos }^{\text{-}1}x=\mathrm{acos}(x)$.

Three functions: sin, cos, and tan, do not require parentheses around their arguments.

cos_d(𝜃), sin_d(𝜃), tan_d(𝜃), sec_d(𝜃), csc_d(𝜃), cot_d(𝜃)

The trigonometry functions listed just above will assume that the argument is in degrees. Real numbers only. Hurmet will subscript the “d” for you.

cosh(z), sinh(z), tanh(z), sech(z), csch(z), coth(z)

Hyperbolic functions or real or complex numbers. Notation for inverse functions is similar to trigonometry.

count(str, pattern)

The number of times string pattern occurs in string str.

dataframe(a, b, …)

Takes vectors as arguments and returns a dataframe.

exp(z)

$e^z$

fetch(url)

Fetches the contents of a remote file. It expects the file to be in TSV format (tab-separated values) and will return a data range. Fetch functions must be stand-alone expressions.

findfirst(searchstring, string)
findfirst(value, vector)
findfirst(booleanVector)

Searches the string (vector) and returns the index of the first occurence of searchstring (value).
If only one (vector) argment is provided, findfirst will return the index of the first true.

findmax(v)

Find the maximum numeric value of a vector. Returns the value and the index. So you would call it this way:
max, index = findmax(𝐕) = ?

floor(x)

floor. Always rounds down. Real numbers only.

gcd(m, n)

Greatest common divisor of two integers.

hcat(v, x)

Horizontal concatenation of: two strings, or two matrices, or an element onto a vector, or a variable onto a map, or a vector onto a data frame.

hypot(x, y)

$\sqrt{x^2+y^2}$   …done in a way that avoids overflow. Real numbers only.

imag(z)

Imaginary part of a complex number.

isnan(x)

Indicates if the argument is not numeric.

length(a)

The length of a string or the number of elements in a matrix or vector.

lerp(X, Y, index)

Linear interplolation. Locates real index within the vector X and returns a real number interpolated from the vector Y. X must contain values in ascending order. Real numbers only.

log(z), ln(z)

Natural (base e) logarithm of real or complex number z.

log₁₀(x)

Base 10 logarithm. Real numbers only. Hurmet will subscript the numerals for you.

log(b, x)

Base b logarithm. Real numbers only.

lfact(n)

Returns the natural logarithm of the factorial of the argument. Valid only for non-negative integers. Note that log(n!) is a valid alias for lfact(n). Real numbers only.

lgamma(x)

Returns the natural logarithm of the gamma function, Γ(x). For now, Hurmet's lgamma(x) function only works on positive rational numbers.

matrix2table(matrix, columnNames, rowNames)

Returns a map with the contents of the matrix. columnNames and the optional rowNames must each be a vector of strings.

$\min (a,b,c,\dots ),\max (a,b,c,\dots )$

Minimum or maximum of a list or array. Real numbers only.

mod(x, y)

x modulo y. This functions divides x by y, and returns the absolute value of the remainder.

number(string)

Converts a string, such as "5" or "3.14" to a number.

ones(m, n)

Returns a m × n matrix filled with ones. Arguments must be integers.

rand(), rand(n), rand(m, n)

Pseudo-random number(s) in the range from 0 to 1 (inclusive of 0, but not 1). Good for Monte-Carlo modeling. Not sufficiently random for crypto.

The optional arguments are integers. rand with no arguments will return a single random number. If one or two arguments are provided, rand will return a matrix filled with random numbers.

real(z)

Real part of a complex number.

rem(x, y)

Remainder. This functions divides x by y, and returns the remainder.

round(x, spec)

Rounds a real number x.
To round to an integer, omit the spec.
To round to n significant digits, write the spec as "rn", e.g., "r3".
To round to n places after the decimal, write the spec as "fn".

sign(x)

Returns $\{\begin{array}{cc}1& \mathrm{i}\mathrm{f}x>0\\ \text{-}1& \mathrm{i}\mathrm{f}x<0\\ 0& \mathrm{o}\mathrm{t}\mathrm{h}\mathrm{e}\mathrm{r}\mathrm{w}\mathrm{i}\mathrm{s}\mathrm{e}\end{array}$
Real numbers only.

string(x, spec)

Takes a number, x, and returns a string. spec is a rounding specification. It can round to a fixed number of digits after the decimal, e.g., "f2", or round to a specified number of digits, e.g., "r3".

sum(a, b, c, …), product(a, b, c, …), length(a, b, c, …), range(a, b, c, …), mean(a, b, c, …), variance(a, b, c, …), stddev(a, b, c, …)

Functions that accumulate a result from a list of arguments or a vector. Real numbers only.

sum(M, n)

Takes a matrix and sums either the rows or the columns.
sum(𝐌, 1) will sum the columns and return a row vector.
sum(𝐌, 2) will sum the rows and return a column vector.

transpose(M)

Transpose a matrix.

vcat(v, x)

Vertical concatenation of: two matrices, or an element onto a vertical vector.

zeros(m, n)

Returns a m × n matrix filled with zeros. Arguments must be integers.

Γ(z)

Gamma function
precision = $\{\begin{array}{cc}100\%& \mathrm{i}\mathrm{f}z\text{ is a positive integer ≤ 100}\\ 15\mathrm{d}\mathrm{i}\mathrm{g}\mathrm{i}\mathrm{t}\mathrm{s}& \mathrm{o}\mathrm{t}\mathrm{h}\mathrm{e}\mathrm{r}\mathrm{w}\mathrm{i}\mathrm{s}\mathrm{e}\end{array}$

Operator Precedence

What is the result of the expression $3+4\times 2$ ?

It depends on whether one does the addition first or the multiplication first. So the answer could be $(3+4)(2)=14$ or it could be $3+(4\times 2)=11$.

To resolve this ambiguity, Hurmet performs operations with the following precedence:

Now let’s return to the question that opened this section. We now know that multiplication has a higher precedence than addition, so the answer to our question above is: $3+(4\times 2)=11$

If Expressions

Hurmet If Expressions enable you to choose between expressions, based upon one or more conditions, as in:

$\beta {}_{\text{1}}=\{\begin{array}{cc}0.85& \mathrm{i}\mathrm{f}f{}_{\text{c}}^{\prime }\le 4,000\\ 0.65& \mathrm{i}\mathrm{f}f{}_{\text{c}}^{\prime }\ge 8,000\\ 0.85-\frac{f{}_{\text{c}}^{\prime }-4,000}{20,000}& \mathrm{o}\mathrm{t}\mathrm{h}\mathrm{e}\mathrm{r}\mathrm{w}\mathrm{i}\mathrm{s}\mathrm{e}\end{array}$

This sort of expression is written between the delimiters: { } The row separator symbol is ; Hurmet will automatically align the logic words if and otherwise. So the example above can be coded this way:

β_1 = {
    0.85                         if f_c′ ≤ 4000 ;
    0.65                         if f_c′ ≥ 8000 ;
    0.85 - (f_c′ - 4000)/20000   otherwise
}

The spaces in that code example are not significant. Hurmet always aligns the words if and otherwise. In fact, that example could also be coded all onto one line. To be precise, the form is:

Conditions may contain logical operators:  and or not ∧  ∨  ¬  ⊻

$x=\{\begin{array}{cc}2a& \mathrm{i}\mathrm{f}a<b\mathrm{a}\mathrm{n}\mathrm{d}b=4\\ a^2& \mathrm{o}\mathrm{t}\mathrm{h}\mathrm{e}\mathrm{r}\mathrm{w}\mathrm{i}\mathrm{s}\mathrm{e}\end{array}$

Chained comparisons are okay.

$x=\{\begin{array}{cc}1.0& \mathrm{i}\mathrm{f}a<b<5<d\\ 1.2& \mathrm{o}\mathrm{t}\mathrm{h}\mathrm{e}\mathrm{r}\mathrm{w}\mathrm{i}\mathrm{s}\mathrm{e}\end{array}$

Summation

Hurmet can handle single-index summation terms. Like this one:
${\displaystyle \sum _{n=0}^{4}2n=20}$

You write the summation expression like this:
\sum_(n=0)^4 2 n = ?

The \sum and ^4 will auto-correct into more descriptive terms and the input text ends up like this:
∑_(n=0)⁴ 2 n = ?.

Overloading

Overloading summary. That is, Hurmet math operators and functions will work on all the data types tablulated below. They also work on a Hurmet quantity that takes any of these shapes:

Also, a unit-less number can be multiplied times a data frame that has numeric values.

Unit-Aware Calculations

Hurmet has a data type called a quantity that contains both a numeric magnitude and a unit of measure. In a Hurmet calculation editing box, you transform a number into a quantity literal by appending a unit name between single quotation marks. Examples:

Hurmet has a unit-aware calculation mode that automatically handles unit conversions on quantities and also checks that the operands are unit-compatible. You specify unit-aware mode by writing two question marks instead of one in the place where you want a result to appear. So if you open a Hurmet calculation cell and write:

4 'ft' + 3 'yards' = ?? m

… the result will render as:

$4\text{ft}+3\text{yards}=3.9624\text{m}$

You can create composite units on the fly and Hurmet will still convert them automatically.

${\displaystyle \frac{3\text{kW}\cdot \text{hr}\times (20\text{min})}{800\text{lbf}\times 1\text{h}}}=1.0116402439486971731\text{km}$

If you try to add quantities with non-compatible units, Hurmet will return an error message:

$3\text{m}+2\text{V}=\text{Error. Adding incompatible units.}$

If the calculated units are non-compatible with the units specified for the result display, Hurmet will return an error message:

$3\text{m}+2\text{ft}=\text{Error. Calculated units are not compatible with the desired result unit:},\text{V}$

If you assign a quantity to a variable, a unit-aware calculation will call the variable’s entire quantity, not just the numeric value.

$L=3\text{ft}$

$L{}_{\text{2}}=2L=2(3\text{ft})=1.8288\text{m}$

If you assign a quantity to a variable, you can still call the variable from a non-unit-aware calculation. Such a calculation will call the scalar value, not the quantity.

$L{}_{\text{unaware}}=2L=2(3)=6$

You’re welcome to view all of Hurmet’s built-in unit definitions.

Currencies

Currency exchange rates change, so Hurmet’s exchange rates are updated with data from the European Central Bank. That update occurs only once per week.

Traditional Units

Many traditional units have had more than one historical definition. Hurmet currently has the following default treatment of certain traditional units:

• pound is treated as a mass, not a force. (lbf and lbm are un-ambiguous alternatives.)

• psf and psi, on the other hand, are treated as force per area.

• ton is treated as a mass, and is the U.S. customary unit. I also put in a tonf, 2000 lbf.

• gallon, fl oz, pint, quart, and bushel are the U.S. customary units.

• Weights are avoirdupois, unless specifically noted as a troy weight.

• point is the adobe point = ¹∕₇₂ inch. TeX point is also available.

• barrel and bbl are an oil barrel = 42 US gallons.

If you are curious about some of the more unusual units, such as “survey foot” or “nautical mile”, I recommend Russ Rowlett’s dictionary of units of measurement.

Numeral display

There are two aspects to how numbers are displayed: (1) decimal separators, and (2) rounding format for results.

Decimal separator

In some countries, the usual decimal separator symbol is a dot. Other countries use a comma. Hurmet starts up with a decimal separator based upon the browser’s language setting. Hurmet also allows the reader (not the document author) to select which display they prefer. Just use the use the drop-down menu labeled Doc | Set Decimal.

The same menu choice also selects how Hurmet displays thousands separators.

This menu choice changes nothing internally. It changes only the display. All Hurmet documents are saved with numbers that have a dot decimal and no thousands separator.

Rounding of Results

Hurmet stores numbers internally as rational numbers in arbitrary precision, but its default result display is a decimal fraction with up to 15 significant digits. You can command Hurmet to display results differently. Just write a format statement into a Hurmet calculation cell. The specified format will apply to every calculation result below that statement (until another format statement). Here’s a format statement example:

format = "f2"

That statement specifies a fixed decimal format. Results after it will display exactly two digits after the decimal. If you would rather specify the number of significant digits, I suggest one of these statements:

format = "r3"
format = "h3"

"r3" will display a result rounded to exactly three significant digits. If your client freaks out because integer values have been rounded and look “wrong”, the "h3" format will round only the fractional part of a number.

That was the short explanation. Now the long one. The rounding format specification string must take the form: "TN∠", where:

Type of rounding

Let N be the number of digits specified. Then:

Numeric result display types f and % can be set to any non-negative integer. The significant digit display types are limited to no more than 15 significant digits.

Tests

Hurmet test statements will send an error message if a criterion is not met. For example, if you assign numeric values to two variables and then write:

The result will be one of these two messages:

If the test fails, the message is also written to the console. So you can run an entire document and get notifications in one place if something has gone wrong. (You can see a browser console by typing Ctrl-Shift-I.)

If you have previously assigned a string to the variable “assert”, a failing test message takes a more informative format:

$\text{T}\text{h}\text{e}\text{c}\text{o}\text{l}\text{u}\text{m}\text{n}\text{a}\text{t}\text{l}\text{o}\text{c}\text{a}\text{t}\text{i}\text{o}\text{n}\text{B}\text{2}\text{s}\text{h}\text{o}\text{u}\text{l}\text{d}\text{w}\text{o}\text{r}\text{k}\text{,}\text{b}\text{u}\text{t}{P}_u\nleqq \varphi R_n$

A test statement takes this form:

If you want a unit-aware comparison, write “@@test” instead of “@test”.

Drawings

Hurmet’s draw environment can plot functions and render simple sketches. For a sine wave, you can open a math zone and type the following code…

draw()
    title "sin x"
    frame 250, 150
    view -5, 5, -3
    axes 2, 1, "labels"
    strokewidth 2
    plot sin(x), 51
    text [1.6, 1.35], "sin x"
end

… which will result in this plot …

Always use x as the variable of a single function. For parametric plots, use t as the variable and put the two expressions into a row vector, like the code below.

draw()
   title "spiral" 
   frame 200, 200 
   view -8, 8 
   axes
   plot [t*cos(π t), t * sin(π t)], 251, 0, 8 
end

… which results in this plot …

You can pass variables into a draw environment. And a draw environment can execute the same statements as a user-defined function. So you can create drawings that change dynamically in reaction to the rest of your document.

I’ll write up an example next week.

Draw environment commands

In the following list, optional arguments are written in orange.

title "string"

Title of the drawing, for accessibility.

frame width, height, position

width and height, in px, define the size of the drawing in the document. position can be "inline", "left", or "right".
This command must come before anything is drawn.

view x_min, x_max, yₘᵢₙ, yₘₐₓ,

This command is usually written directly after frame. The arguments set the coordinate system. If y_min is omitted, the x-axis is placed in the middle of the picture. If y_max is omitted, the scales along the x-axis and y-axis are the same.

axes dx, dy, "labels"

Draws coordinate axes.

grid dx, dy, "labels"

Draws a background grid.

stroke "color"

Sets the default color for lines, paths, curves and outlines of solid figures. Can be any of the standard HTML predefined color names.

strokewidth pixelvalue

Sets the width of lines, paths, and shape outlines.

strokedasharray "dashpixel spacepixel"

Set a pattern of dashes and gaps for lines and paths. Default = null.

fill "color"

Sets the default color for filling in the inside of solid figures.

fontfamily "sansserif" | "serif" | "fixed" | "monotype"

Sets the font type.

fontsize pixelvalue

Sets the font size in px. Default = 13.33 (~10 pt).

marker "none" | "dot" | "arrow" | "arrowdot"

Sets the default marker symbol that is drawn at the endpoints of lines and paths. Dots are also set along the intermediate points of paths and curves.

line [x, y; u, v]

Draws a straight line from coordinate point x, y to coordinate point u, v.

path [x₁, y₁; x₂, y₂; …; xₙ, yₙ], "L", or "T", or [r₁; r₂; …; rₙ]

Draws a path connecting all the points in the matrix.

The second (optional) argument defines the type of line segments. "L" will draw straight segments. "T" will fit a curve to the points. A vector of numbers will define arc radii for each segment (0 indicates a straight line segment).

curve [x₁, y₁; x₂, y₂; …; xₙ, yₙ]

Fits a quadratic bezier curve to each point.

circle [x, y], r

Draws a circle of radius r, centered at point x, y.

dot [x, y], "open" | "closed", "label", position

Draws a dot with an optional appended label. position can be: "above"|"below"|"left"|"right"|"aboveleft"|"aboveright" |"belowleft"|"belowright"|null

ellipse [x, y], rx, ry

Draws an ellipse of radii rx and ry, centered at point x, y.

arc [x, y; u, v], r or [rx, ry]

Draws an arc in anticlockwise direction from point x, y to point u, v. It will be either a circular arc of radius r or an elliptical arc of radius [rx, ry].

rect [x, y; u, v], r

Draws a rectangle with corners at points x, y and u, v. The optional r argument defines the corner radius of a rounded rectangle.

text [x, y], "string", position

Writes the string at a point keyed to coordinates x, y.

position can be "above", "below", "middle", "left", "right", "aboveleft", "aboveright", "belowleft", or "belowright". The default is "middle".

The string can be styled with Markdown inline styles: _italic_, **bold**, `code`, ~_subscript~, and ~~strikethrough~~.

leader [x₁, y₁; x₂, y₂; x₃, y₃; etc], "note"

Writes a note with an arrow pointing to a location.

dimension [x₁, y₁; x₂, y₂; x₃, y₃; etc; xLabel, yLabel], "label" or ["label₁", "label₂", etc.]

Writes a string of dimensions. xLabel and yLabel locate the labels. The other points each define a witness line.

plot f or [g, h], 𝑛, xₘᵢₙ, xₘₐₓ

Plots a function or a pair of parametric equations. A single function f() should be written with x as its variable. A pair of parametric equations should be written with t as their variable.
Values will be plotted from xₘᵢₙ to xₘₐₓ. n determines the number of points to be plotted. (Default = 250)

User Defined Functions

If Hurmet’s built-in functions do not satisfy your needs, it is possible to write your own functions. Example:

function multiply(a, b)
   return a × b
end

Other Hurmet calculation cells can then call the function:

$n=\mathrm{multiply}(2,4)=8$

Unlike other Hurmet assignments, user defined functions can be placed at the end of the document and still be called by other expressions.

The function can have any number of arguments, or none, separated by commas. The function name and each argument (if any) must be valid identifiers.

If any arguments are optional, write them after a semi-colon and provide a default value.

function Ms(section, Fy, Lb; Cb = 1, axis = "x")

Function statements end at a line ending, unless the last character is one of: ( [ { , ; + - or the following line begins with one of: } ] )

Comments can be written after #. A space must precede the #.

Variables created inside a user-defined function are local and their values will not be available outside the function. A user-defined function returns only the result of the expression in a return statement.

If you omit any arguments when you call a function, Hurmet will fill out the argument list with values of undefined when it executes the function.

Hurmet does not support function recursion.

Code Blocks

Inside a user-defined function, Hurmet supports code blocks and some additional control words. That is, words such as if and else can control execution of a block of statements, not just one expression. Statements between the if statement and an end statement are in the block. Example:

if a ≤ b
    x = a + b²
    y = 2 x
end

Indentation is not significant to the parser but is very useful to humans reading the code. I usually indent by four spaces.

if else

if​​…else control words make the execution of code blocks dependent on a condition. Example:

if a ≤ 4000
    b = 0.85
elseif a ≥ 8000
    b = 0.65
else
    b = 0.85 - (a - 4000)/20000
end

while

A while loop executes a code block repeatedly, as long as a condition holds true. Example:

while b ≠ 0
    h = b
    b = mod(a, b)
    a = h
end

for

A for loop iterates, executing a code block once with each element of a range or collection.

Examples:

sum = 0 for i in 1:10 sum = sum + i end

reverse = "" for ch in "abcdef" reverse = ch & reverse end

The index variable of a for loop will iterate through each of the numbers in a range, the elements in a matrix, or the characters in a string.

break

A loop can be terminated early via the break keyword. Example:

for i in 1:1000000
    if i ≥ 2
        break
    end
end

return

A return statement terminates the function.

If the optional expression is present, the function will return its result. If not, the function will return undefined.

throw

A throw statement terminates the function and returns an optional error message.

print

A print statement writes a message to the browser’s console. You can type Ctrl Shift I to see it. Such a message can be very useful while debugging a function.

one-liner

To make early returns less verbose, a one-liner if syntax is available:

startSvg

A user-defined function can also operate as a draw envronment. To initiate a draw environement, write the following line of code into a function:

svg = startSvg()

After that line is written, all the draw environment commands are valid.

Remote modules

If some Hurmet code is used repeatedly, it makes sense to write that code once and import it into other documents. Hurmet modules are text files that serve that purpose. Modules can contain functions and statements that assign literal values to a variable. Such a module would have text that might look like this:

E = 29000 'ksi'

v = [4, 6, 8]

function multiply(a, b)
    return a × b
end

A Hurmet document can load an entire module into one variable with a import statement. The following statement will import a file that contains the text above.

mod = import("https://hurmet.org/smallModule.txt") = !

After a module has been imported and loaded into a variable, its functions and values can be called by writing the module name and variable/function name in dot notation, as in:

E = mod.E = ?? psi

n = mod.multiply(2, 4) = ?

Imported Parameters

The Hurmet variable name importedParameters has a special purpose. It loads module values into multiple variables instead of into one variable. An example of such an import is:

importedParameters = import("https://hurmet.org/parent.txt") = !

That statement will render like this:

Such a statement is handy in a big project, where you break the calculations into several documents. Since any big project often has several common variables, you want a way to keep them synchronized. Put an importedParameters statement into each of the documents and you’re good. As an added benefit, a reviewer can see what you are doing.

Macros

A macro enables you to save typing. You type the macro name, hit Alt-E, and a larger section appears in your document. The macro name serves as an abbreviation for the macro expansion.

A Hurmet macro is written in a module. The macro expansion is a section of a Hurmet document, written in Markdown format. The expansion is contained within """…""" delimiters. Here’s an example:

ab = """¢` A_b = (π d_b^2) / 4 = ?? in² `, bolt area"""

As you can see, the macro expansion contains an equation to find the area of a bolt. That expression is written into a module. If you’re writing macros, you typically write several macros into each module.

A user can invoke the macro in two steps. First, import the module into a document, as in this example:

macros = import("https://gist.githubusercontent.com/ronkok/317f8ce0f706608fa9b3e3258ecea138/raw/csMacros.txt") = !

Then the user types the macro name, ab, and hits Alt-E. The macro expansion appears in the document.

It doesn’t really matter what you name the module. When a user invokes the Alt-E command, Hurmet will search all active variables to see if they contain the desired macro name.

Gists

Hurmet is a web app, so it can import text files only from addresses that begin with http or https. An easy way to create such a file is a Github Gist. I've written an example Gist for imported parameters:

If you create your own Gists, you'll see that the addresses of the raw files are very long. If you want a permalink to your file, delete the 40 random characters after "/raw/". Github keeps a copy of every draft of your file and the random part after "/raw/" is the revision ID.

Batch Mode

Suppose you want to operate in batch mode and run the calculations on an entire document, or multiple documents, all at once. You can do that.

There is an altenate version of Hurmet that runs in Node.js from a command-line interface (CLI). It exposes one method, md2html(), which takes Markdown input and returns an HTML document. The code below shows how one might apply it in Node.js:

// Read a Markdown file, run the calcs, and write an HTML file.
const fs = require('fs')
const hurmet = require('filePath/hurmet.cjs')
const temml = require('filePath/temml.cjs') // Math rendering library
globalThis.temml = temml
const titleRegEx = /([^.\\/]+)\.md$/;  // A helper.

// The main function has to be async.
(async function main() {
  const inputPath = 'filePath/fileName.md'
  const title = titleRegEx.exec(inputPath)[1];
  const outputPath = `filePath/${title}.html`
  // Read the file.
  const md = fs.readFileSync(inputPath).toString('utf8')
  // Run the calculations and convert to HTML.
  const html = await hurmet.md2html(md, title)
  fs.writeFileSync(outputPath, html)
})();

In the code above, you need to customize the filePath and fileName callouts.

The HTML file <head> contains references to a CSS (style) file and two fonts. You can get those files, and the hurmet.js file that runs all this, from Hurmet’s GitHub repository. Find the green button labeled “code” and get a zip file.

In that zip file, the preview folder contains the files: hurmet.js, styles.css, latinmodernmath.woff2, and Temml.woff2. The CSS and font files need to be copied to the same folder as your HTML files.

Troubleshooting

Typing lag

A big document with a lot of math may cause typing lag. You can regain speed by clicking on the Draft Mode toggle button at File | Draft mode. It will render math as plain text and omit the blue echos.

Matrix multiplication

To get element-wise multiplication of two matrices, the operator symbol must be explicitly written as ∘ or .*.

Offline

If Hurmet does not work offline, it may be because the browser is deleting cookies. If that is the case, whitelist "hurmet.org".

Gists

Hurmet can export or import a document in Markdown format. This is useful for collaboration.

Say that you have written a calculation. It’s awesome and you want to share it so that others can use it as a template. An easy way to share work is via a GitHub Gist. Then anyone can view it, download it, or comment on it. Here’s an example.

Hurmet’s version of Markdown adds some extensions that GitHub does not recognize, such as calculation cells, indented paragraphs, and merged cells in tables.

Coming Attractions

• A distribution data type, to enable calculations with uncertainty

• A date data type

Other Resources

Civil and structural engineers may also find these items useful:

• Concrete Column Interaction Diagram

• Fetchable TSV files with steel shape data: wide flanges, channels, HSS, pipes, tees, double angles, HP, and MS.

• Importable module with functions for steel member strength.

• A set of macros for civil and structural engineers. Here’s a description and a link to the source.

Credits

I’m Ron Kok and I created Hurmet because I want practicing engineers to have the tools they need to write calculations that are clear, complete, and reviewable.

Hurmet is built with the aid of several open source libraries and resources, for which I am very grateful.

• ProseMirror, an extendable rich-text editor by Marijn Haverbeke.

• Temml, a LaTeX-to-MathML library.

• CodeJar, a light-weight text editor, by Anton Medvedev.

• Many of Hurmet’s menu buttons show images from icomoon.

• This document’s railroad diagrams are modified versions of images created with regexper.com, by Jeff Avalone.

Copyright © 2020-2024 Ron Kok. Released under the MIT License