Home / Articles / Calculations You Can Defend HES-03
Sign and Direction Conventions: The Quietest Error in Calculations
Is an azimuth measured from south or from north? Does a positive shear stress rotate clockwise or counter-clockwise? These questions look simple; yet five of the errors found in this site's audit came from exactly these questions. None of them was a formula error.
1. An error without a formula
Most errors in an engineering calculation do not come from a wrong formula. The formula is right; but two parts read the same quantity with different conventions. One measures an angle from north, the other from south. One counts counter-clockwise as positive, the other clockwise. Each part is correct on its own; where they meet, the result is wrong.
2. Five examples
Five such cases were found in the archi-civil.com audit:
| Where | Rule stated | Rule applied | Consequence |
|---|---|---|---|
| Sun azimuth | Measured from south, east negative | Measured from north | 180° at noon (correct: 0°) |
| Kinetic facade | Facade direction: 0 = south | Sun measured from north | South facade "sun behind" at summer noon |
| Mohr circle | Label: "positive τ = clockwise" | Engine: positive τ rotates counter-clockwise | A user following the label gets the principal direction wrong |
| Cantilever | Text: "Ma clockwise" | Physics: fixed-end moment counter-clockwise | The free-body diagram is drawn wrong |
| Reference solver | End moments: counter-clockwise + | Sign reversed in the reaction formula | A correct page looked 107% wrong |
What the five share is that the error is neither inside the code nor in a formula. It is between two things: between a convention and the calculation that uses it, between an engine and the label that describes it.
3. Why so quiet?
Sign and direction errors usually produce plausible-looking results. A sun azimuth of 180° is a number, not an error message. A moment with the wrong sign looks right at first because its magnitude is right. These errors neither crash a program nor produce an "impossible" value; they only lead to a wrong decision.
The second reason is that tests are written with the same convention. The kinetic facade test represented the south facade with 180°, sharing the engine's wrong convention (see HES-01). A test that shares the convention cannot see a convention error.
4. Writing the convention at the boundary
The most effective safeguard is to state the convention at every boundary: at a function's input and output, on an interface label, in a table header. The field in the solar engine was named "azimuthFromSouth", so the convention was in the name. The error was the divergence between what the name said and what the calculation did. Because the convention was written down, the error could be found.
The fixes applied the same principle: the solar and kinetic facade engines now state "from south, east negative, west positive" in the same words in both the code comment and the interface label. In the Cross example, the sign convention of the results was written into the text: "end-moment convention, same as FEM (left end −, right end +)".
5. Testing with physical facts
The most reliable way to catch convention errors is to test against physical facts independent of the convention:
- Sun: in the northern hemisphere the sun is due south at noon and rises in the north-east on a summer morning. Morning and evening azimuths are symmetric.
- Shading: on a summer noon the south facade gets sun and the north facade does not.
- Mohr circle: in pure shear the principal tension direction makes 45° with the x axis; the sign of τ only decides which way.
- Cantilever: a downward load to the right turns the beam clockwise about the fixed end; the support balances it counter-clockwise.
Each of these facts is now a check in the site's tests.
6. Checklist
- For every angle: measured from where? Which direction is positive?
- For every force and moment: which sign is tension, which compression? Which rotation is positive?
- Is the convention written on the label that shows the value?
- Does the test check the convention against a physical fact independent of the code?
- Where two parts meet (engine and interface, two engines, engine and test), do both use the same convention?
References
- archi-civil.com release notes (README), v565, v566, v569, v571: sign and direction convention errors and their fixes.
- Duffie, J. A. and Beckman, W. A. (2013). Solar Engineering of Thermal Processes, 4th ed., Chapter 1 (solar angles and sign conventions). Wiley.
- Beer, F. P., Johnston, E. R., DeWolf, J. T. and Mazurek, D. F. Mechanics of Materials, Chapter 7 (stress transformation and Mohr's circle). McGraw-Hill.
The numbers in this article were produced by the site's engines; code values are given with their clause numbers.