> ## Documentation Index
> Fetch the complete documentation index at: https://calcs.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Template Conventions
> Standards and conventions for creating consistent Calcs.com templates
An overall goal is for Calcs.com to be as simple as possible for users, and require as little interpretation as possible. While easy with just a few sheets, as they multiply in number, we should articulate what conventions to use so as to keep it as simple as possible.
## General Strategies
The main points to follow are:
Engineers are used to looking at the building codes and used to the symbols and terms used in those codes. Wherever possible, Calcs.com should use the same. Further, all variables and intermediate calculations that are used in the codes/specs should also be shown in the Calcs.com sheets.
All sheets should be as consistent as possible between each other. A timber beam is not the same as a steel beam - but there are a lot of similarities, and so any terminology or symbol or heading or widget that can be the same between both sheets should be the same.
Inputs should generally be ordered from simplest and most important to complex and least important. If a user is unlikely to need to change something, or if a conservative assumption will be adequate in most cases, then it should be far down the page, collapsed, and/or at the bottom of a heading. Also, inputs should generally be at the top, and outputs at the bottom.
If an equation or check is defined in the code, then it should be referenced.
Within a calculation, fields should be read downwards and displayed in the order in which they're calculated. For example, in a Shear Capacity section, if V\_d = phi\*V\_u, and V\_u = min(V\_y, V\_b); then V\_y and V\_b widgets should appear first, then V\_u below those, then V\_d at the bottom of the box.
Not all of these points will always be able to be met - such as if the steel beam code uses a different symbol than the timber beam code for an equivalent dimension. See below for some of the most common such conflicts and how to resolve them.
## Axis Labels
There are three sets of axes that we use in our terminology:
### 1. Local Axes (lower-case x,y,z)
All input and most computed fields should be referring to these.
* The `z` axis is parallel to the length of the member
* The `x` axis is the `strong axis` or `major axis` (for a beam, this is usually parallel to the ground)
* The `y` axis is the `weak axis` or `minor axis` (for a beam, this is usually the axis perpendicular to the ground)
* The `x` axis is parallel to the length of the member
* The `y` axis is the `strong axis` or `major axis` (for a beam, this is usually parallel to the ground)
* The `z` axis is the `weak axis` or `minor axis` (for a beam, this is usually the axis perpendicular to the ground)
### 2. Global Axes (upper-case X,Y,Z)
Used mostly only when talking about a frame or the structure as a whole.
* The `Z` axis is perpendicular to the ground
* The `X` axis is the long axis of the structure (its length)
* The `Y` axis is the short axis of the structure (its width)
### 3. Plotting Axes (x,y,z)
Avoid using these in any public-facing pages, to avoid user confusion. They only relate to the graphical plots shown on a sheet.
* The `z` axis is perpendicular to the screen
* The `x` axis is horizontal on the screen. Beams should be plotted parallel to this axis
* The `y` axis is vertical on the screen. Columns should be plotted parallel to this axis
## Standard Headings
Headings should be listed in the following order, as appropriate:
1. **Key Properties** - Don't use `Dimensions`, `Geometry`, `Section Properties`, or other such terms
2. **Permanent and Imposed Loads (AS1170.1)** (AU design sheets) - Don't use just `Loads` in design sheets
* `Dead and Live Loads` (US design sheets)
* `Loads` (analysis sheets)
3. **Other Loads (AS1170.x)**
4. **Load Case Analysis (AS1170.0)** (AU) or `Load Combinations` (US)
5. **Axial Capacity (ASxxxx, Cl yy.zz)**
6. **Shear Capacity (ASxxxx, Cl yy.zz)**
7. **Moment Capacity (ASxxxx, Cl yy.zz)**
8. **Combined Load Capacity (ASxxxx, Cl yy.zz)**
9. **Deflection (ASxxxx, Cl yy.zz)** (beams) or `Deformation (ASxxxx, Cl yy.zz)` (columns)
10. **Summary** (shown on the right column of the page)
### Key Properties Fields
#### Dimensions
* `Total Length` = `L` (Don't use Total Span Length)
* `Position of Supports` = `r`
* `Type` = `Pinned` or `Fixed` drop-down
* `Position`
* `Cross-section Width` = `b` (Don't use `w`, which gets confused with distributed loads)
* `Cross-section Height` = `h`
* `Cross-section Thickness` = `t` (Relevant mostly only for steel)
#### Loads
* `Axial Load` = `F`
* `Area Distributed Load` = `w`
* `Load Width` (AU) or `Tributary Width` (US)
* `Dead Load`
* `Live Load`
* `Start`
* `End`
* `Distributed Load` = `q` (computed - detail view only)
* `Point Load` = `P`
* `Applied Moment` = `M`
* `Include Self-Weight` = `Yes` or `No` drop-down
* `Character of Imposed Loads` = drop-down with options
#### Capacity Factors
* `Capacity Factor` = `φ_N` (Axial)
* `Capacity Factor` = `φ_V` (Shear)
* `Capacity Factor` = `φ_M` (Moment)
#### Summary Values
* `Design Axial Compression` = `N*_c`
* `Axial Compression Capacity` = `N_d,c`
* `Design Axial Tension` = `N*_t`
* `Axial Tension Capacity` = `N_d,t`
* `Design Shear` = `V*`
* `Shear Capacity` = `V_d`
* `Design Moment` = `M*`
* `Moment Capacity` = `M_d`
* `Combined Moment and Shear` = `D*`
* `Design Axial Compression` = `N_u,c`
* `Axial Compression Capacity` = `N_n,c`
* `Design Axial Tension` = `N_u,t`
* `Axial Tension Capacity` = `N_n,t`
* `Design Shear` = `V_u`
* `Shear Capacity` = `V_n`
* `Design Moment` = `M_u`
* `Moment Capacity` = `M_n`
* `Combined Moment and Shear` = `D`
## Sign Conventions
Signage convention can be confusing when used in conjunction with language. The purpose of this section is to clarify signage conventions both for developers and users.
### Default Positive Values
The proposed default positives are:
* Loads applied **downward**
* Deflection **downward**
* **Counter-clockwise** moments (by right hand rule)
* **Compression**
* Shear
* Bearing - **down**
* Lateral Earthquake - **Left**
* Wind **Left**
### Default Negative Values
Consequently, the proposed default negatives are:
* Loads applied **upward**
* Deflection **upward**
* **Clockwise** moments
* **Tension**
* Bearing - **uplift**
* Lateral Earthquake - **Right**
* Wind **Right**
Note that this means language preceding the value does not negate the negative. i.e. Wind,up and Wind,dn are applied *in the same direction if the signage is the same* i.e. both +ve or both -ve.
### Absolute Values
Values reported as absolute values should be reported as such. Examples include:
* Deflection limits
* Bending moment limits
* Shear limits
* Bearing capacity
### Current Implementation Notes
#### Confusions
* Absolute value used in various steps of the calc - this makes tracking if a number is actually +ve or just abs() more difficult
* Eccentricity direction - how is this defined?
* Is negative always down or up?
* Loads: positive is downward force
* Deflection: -ve is down and typically taken as abs() value when checking limits
* Moment: -ve is hogging moment 'up'
* Positive moment is shown as Clockwise on diagram
* Wind up vs wind down interpretation
* Shear is abs() in some templates
* Which side is which with horizontal and vertical earthquakes?
#### Potential Solutions
* Limit use of abs() to certain locations in the template
* Apply eccentricity by default in both directions
* Consistent use of signage with clear documentation
* Add more diagrams
* Manipulate solver to add wind down as -ve for consistency
## Best Practices
Always document any deviations from these conventions in your template's documentation, especially when code requirements differ from the standard conventions.