Custom calculation

Your own calculation sheet, printed in the standard report and saved in projects like any other calculation: variables with units, formulas shown as written, then with the values substituted, then evaluated with units, narrative text, headings, code references and pass / fail checks. Units are part of every value, so adding a length to a force, or comparing a moment with a stress, is an error shown on that cell, not a wrong number. You are the engineer of record: the method, the references and the limits on the sheet are yours.

Inputs of the custom calculation #

• Title: the calculation's heading in the report.
• Cells, in the order they print. Each cell has a kind:
  • Variable: a name and a value with its unit, for example L = 20 ft, w = 1.2 kip/ft, Zx = 54.6 in^3, fc = 4000 psi, phib = 0.90. A variable may also be a short formula (12 ft + 6 in).
  • Formula: a name and an expression of other names, for example Mu = w*L^2/8. The report shows Mu = w × L² / 8 = (1.2 kip/ft) × (20 ft)² / 8 = 60 kip-ft.
  • Check: a comparison, for example Mu <= phiMn, with a title and a reference. It reads OK or NG like any check and counts in the calculation's status; <= and < give the ratio left / right, >= and > right / left.
  • Text (up to 500 characters), Heading, and Code reference (what the provision says, and its section).
  • Display unit (variables and formulas): the unit the result is shown in, for example kip-ft or kN-m. Left empty, the unit follows from the values (kip/ft × ft² reads kip-ft; ksi × in³ reads kip-in).
  • Reference: the code section, table or source of the cell (AISC 360-22 Eq. F2-1).
• Units switch: shows every result in US or metric units (kip -> kN, ft -> m, ksi -> MPa, psf -> kPa); a display unit you entered is shown as its counterpart in the other system. What you typed is never changed.

Cells may be in any order: each one is evaluated after the cells it names. A sheet holds up to 150 cells.

Writing expressions #

Names start with a letter and may hold digits, _ and ' (fc, f'c, phiMn, Mu). A leading Greek word prints as its letter: phiMn prints φMn, lambda prints λ, DeltaL prints ΔL. Unit names may also be variable names, because a unit is read only right after a number or in brackets; to divide a number by a variable whose name is a unit, put the variable in parentheses (10 ft / (h)).

Units: length in, ft, yd, mi, mm, cm, m, km; force lbf (lb), kip, N, kN, MN, kgf; mass kg, g, tonne, lbm; time s, ms, min, h; frequency Hz, rpm; temperature difference degF (°F), degC (°C), K; stress and pressure psi, ksi, psf, ksf, Pa, kPa, MPa, GPa, bar; line load plf, klf; unit weight pcf, kcf; energy and power J, kJ, W, kW; speed mph; angle rad, deg (°); percent %. Factors are the exact NIST SP 811 definitions (1 in = 25.4 mm, 1 lbf = 4.4482216152605 N).

Empirical equations with √f'c. ACI writes √f'c with f'c in psi and the result in psi. Write it so the units say so: 2*lambda*sqrt(fc/[psi])*[psi]*bw*d: the root of the number of psi, times 1 psi.

There is no auto-design: the sheet is yours, nothing on it is a design variable the program could know.

Checks performed #

The report prints the whole sheet in order as the Calculation sheet table (in the Summary of Checks), then each formula and check step by step.

Limitations #

• No user-defined functions, conditionals (if / else), tables, loops, matrices or vectors. Each check holds one comparison.
• Temperatures are differences: °F and °C convert by 5/9 with no offset. Enter a temperature change, not a reading.
• Plain numbers in trigonometric functions are radians.
• Expressions are limited to 300 characters, 200 symbols and 40 levels of nesting; exponents to ±1000. This keeps a mistyped or hostile entry from tying up the server.
• Results print to four significant figures.
• The units switch converts what is shown; text cells and headings print as typed in either system.

Verification examples #

Verification status: 8 values compared in 3 examples (3 published, 0 hand calculations from the cited equations): 8 within tolerance, 0 recorded deviations. Code basis: the provisions it uses were read in the target edition.

Published examples typed as sheets (tests/test_verify_custom_calc.py):

The parser is tested against hostile entries (attempts to reach Python, attribute access, subscripts, huge exponents, deep nesting, very long expressions): each stops with a message in a fraction of a second (tests/test_custom_calc.py).