Sign Conventions

Getting sign conventions right is one of the trickier parts of structural analysis software. This page documents the conventions used throughout Armatura, with references to where they originate.

If you encounter results that seem to have the wrong sign, check this page first — the mapping between section properties, local axes, and global axes is where most confusion arises.

Global coordinate system

Right-handed Cartesian:

• X — primary horizontal axis (typically along the structure)
• Y — secondary horizontal axis (transverse)
• Z — vertical axis, positive upward

Gravity acts in the −Z direction. This follows standard structural engineering convention and is consistent with [MAS] throughout.

Member local coordinate system

Each member has a local coordinate system derived from its geometry and orientation vector:

• Local x — along the member axis, from start node to end node
• Local y — perpendicular to x, determined by the cross product of local z and local x
• Local z — direction of the orientation vector component perpendicular to local x (Gram–Schmidt orthogonalisation)

This is the CALFEM convention from [CALFEM] §5.6 (the eo parameter of beam3e).

Default orientation vectors

For non-vertical members, the default orientation vector is global Z = (0, 0, 1). This places local z roughly upward, which means the section's strong axis (Ixx) resists vertical bending — the expected behaviour for horizontal beams.

For vertical members (where global Z is parallel to the member axis and cannot be used), the default is global X = (1, 0, 0).

Users can override the orientation vector per member via Member.OrientationVector to control how the section is rotated about the member axis.

DOF ordering

Each node has 6 degrees of freedom, ordered as:

Index	DOF	Description
0	Ux	Translation in global X
1	Uy	Translation in global Y
2	Uz	Translation in global Z
3	Rx	Rotation about global X
4	Ry	Rotation about global Y
5	Rz	Rotation about global Z

This ordering follows [MAS] §8.3, p. 462.

Section property mapping

This is where most confusion tends to arise. The mapping between section-level properties and element-local properties is:

Section property	Element property	Resists bending in	Causes deflection in
Ixx (about section x-axis)	Iy (about local y)	x-z plane	local z direction
Iyy (about section y-axis)	Iz (about local z)	x-y plane	local y direction

This mapping is fixed — it does not change based on member orientation. The orientation vector system ensures that local z aligns with the section's physical depth direction, so Ixx → Iy is always the correct assignment. There is no conditional swapping of inertias.

This is the same philosophy as CALFEM: the beam3e function receives Iy and Iz already in local coordinates. The difference is that CALFEM expects the user to resolve this manually, while Armatura handles it through the orientation vector.

See [MAS] §8.3, p. 469 (note after Eq. 8.39) for the relationship between inertias and bending planes.

Forces and moments

Applied loads

Forces are specified in global coordinates. A gravity load on a beam is applied as a negative Z force:

// 3 kN/m downward
new UniformDistributedLoad(loadCase, member, new Point3D(0, 0, -3000));

Moments follow the right-hand rule about each global axis.

Reactions

Reactions are reported in global coordinates. A positive Rz reaction means the support pushes upward (resisting a downward load).

Internal forces

Internal forces from GetInternalForcesAt() are reported in member local coordinates:

Index	Force	Sign convention
0	N (axial)	Positive = tension
1	Vy (shear in local y)	Positive in local +y direction
2	Vz (shear in local z)	Positive in local +z direction
3	Mx (torsion)	Right-hand rule about local x
4	My (bending about local y)	Right-hand rule about local y
5	Mz (bending about local z)	Right-hand rule about local z

For a horizontal beam along global X with a downward load (−Z), positive My at midspan corresponds to a sagging moment. This follows from the right-hand rule: curling the fingers of the right hand from +z toward +x gives the positive My direction.

Fixed-end forces

Equivalent nodal forces for distributed loads use the sign convention from [MAS] Chapter 6 (inside front cover table). A subtlety that is worth understanding: the 2D beam convention (counterclockwise positive) maps to the 3D DOF convention with a sign relationship that depends on the bending plane. For bending in the x-z plane, the coupling term in the stiffness matrix is k[2,4] = −6EI/L² (negative), which means the moment DOF (θy) has the opposite coupling sign compared to the analogous 2D term. The fixed-end force formulas account for this.

This is one of those details that is easy to get wrong — if you are implementing your own element formulations, verify carefully against both cantilever and simply supported benchmark cases. A sign error that produces correct results for one support condition can give wrong results for another.

Distributed loads

Load intensity is specified in global coordinates. The solver transforms loads to local coordinates internally using the element's transformation matrix.

// 3 kN/m downward (global −Z)
new UniformDistributedLoad(loadCase, member, new Point3D(0, 0, -3000));

// 5 kN/m lateral (global +Y)
new UniformDistributedLoad(loadCase, member, new Point3D(0, 5000, 0));

Member end releases

Release DOFs are specified in member local coordinates. Releasing Ry and Rz at a member end creates a pin that allows rotation about the local y and z axes.

References

• Kassimali (2015), §8.3, p. 462: DOF ordering and sign conventions for 3D frames
• Kassimali (2015), §8.3, p. 469: section inertia to element stiffness mapping
• Kassimali (2015), Chapter 6: equivalent nodal forces and fixed-end force tables
• CALFEM Manual §5.6: beam3e orientation vector and local axis convention