Calculation packages

Why this matters

On a real project, a calculation is not a scrap of paper that gives you a number. It is a record: evidence that the design meets its criteria, which a checker reviews, a licensed engineer relies on when sealing drawings, and which may be read years later after a failure, a renovation or a dispute. A calculation that cannot be followed by someone else is, for practical purposes, a calculation that was never done.

The core idea: a calc package anyone can check

Firms have their own templates, but a good calculation packageA record of a design calculation, with criteria, assumptions, sourced inputs, method, units, results and revisions, that someone else can check. almost always contains:

1. Cover sheet: project, calc number and title, revision, originator, checker, approver and dates.
2. Purpose and scope: what is being calculated and what is not ("gravity design of beam B3; lateral loads by others").
3. Design criteria and references: the governing codes and standards with edition, client criteria, and the basis of design.
4. AssumptionsStated conditions the calculation relies on, such as support conditions or material grades, marked when they still need confirming.: support conditions, material grades, load sources. Mark any that must be confirmed later ("assumed; to be verified by survey").
5. Inputs, with sources: every number has a source (a drawing, a vendor data sheet, a code table, a previous calc).
6. Method: the formula or software used, and why it applies.
7. Calculations with units at every step.
8. Results and conclusion: a short summary table: demand, capacity, ratio, OK or not.
9. Revision logThe part of a calc package that records what changed in each revision and why.: what changed in each revision and why.

Units at every step

Most calculation errors that reach a checker are unit errors: kN mixed with N, mm⁴ with m⁴, kip-ft with kN·m. Two habits prevent them:

• Convert to one consistent system first (for example SI base units: N, m, Pa) and convert results back only for reporting.
• Write units on every line and check that they cancel. If you expect metres and get N·m, something is wrong.

Useful conversions to know: 1 GPa = 10⁹ Pa; 1 mm⁴ = 10⁻¹² m⁴; 1 kip = 4.448 kN; 1 ft = 0.3048 m; so 1 kip-ft = 1.356 kN·m; 1 psf = 47.88 Pa.

In Python, unit libraries such as pintA Python unit library that attaches units to numbers and raises an error when incompatible units are combined. attach units to numbers and raise an error if you add metres to newtons. In spreadsheets and Mathcad-style tools, keep a units column next to every value.

Worked example: a textbook beam check

This is a classroom exercise to show the format, not a design. A simply supported steel beam spans L = 6.0 m and carries a uniform service load w = 10 kN/m. Take E = 200 GPa and I = 80 × 10⁶ mm⁴.

Convert to SI base units:

w = 10 kN/m        = 10 000 N/m
L = 6.0 m
E = 200 GPa        = 200 × 10^9 Pa
I = 80 × 10^6 mm^4 = 80 × 10^6 × 10^-12 m^4 = 8.0 × 10^-5 m^4

Reactions and moment (standard simply supported beam formulas):

R     = w L / 2   = 10 000 × 6.0 / 2   = 30 000 N    = 30.0 kN
M_max = w L^2 / 8 = 10 000 × 36 / 8    = 45 000 N·m  = 45.0 kN·m

Midspan deflection:

δ = 5 w L^4 / (384 E I)
  = 5 × 10 000 × 1296 / (384 × 200 × 10^9 × 8.0 × 10^-5)
  = 6.48 × 10^7 / 6.144 × 10^9
  = 0.01055 m = 10.5 mm

Unit check: (N/m × m⁴) / (Pa × m⁴) = (N·m³) / (N/m² × m⁴) = m. Good.

Serviceability check against a deflection limitThe maximum allowed deflection, often written as span divided by a number such as L/360, set by the code and project criteria. of L/360 (a limit commonly used for floor live load; the governing code and the project criteria set the limit for each case):

allowable = 6000 mm / 360 = 16.7 mm
ratio     = 10.5 / 16.7   = 0.63   -> OK

A real beam design would also need the governing load combinations, strength checks for bending and shear to the applicable steel standard, lateral-torsional buckling, connections and vibration, all under the review of a licensed engineer. This example shows only how to set out and check a calculation.

Writing calcs in Python

A script or notebook can be a fine calc package if it reads like one: a docstring header with calc number and revision, named inputs with sources in comments, one function per formula, units in every variable name or comment, and a printed results table. Because it is code, it can be re-run when an input changes, and the checker can test it with known cases (for example a hand-calculated example from a textbook).

Common mistakes

• Numbers without sources. "w = 10 kN/m" from where? Cite it.
• Mixed units. mm and m in the same formula.
• Hidden assumptions. Pinned supports assumed but never stated.
• No conclusion. The reader should not have to hunt for "OK" or "not OK".
• Editing a checked calc without a new revision. Any change after checking needs a revision and a re-check.

Quick recap

• A calc package is a record someone else must be able to follow and check.
• Include criteria with editions, assumptions, sourced inputs, method, units, results and a revision log.
• Convert to consistent units first and check that units cancel.
• Code-based calcs are welcome if they are readable, tested and versioned; real designs still need licensed review.

Try it

Open the Do tab and finish a small Python calc package: convert the inputs, compute the deflection and write the check.