A Vector in the x-z Plane

Three-dimensional frame elements require user input for the local element axes. Although the local x axis points from node I to node J, there is no automatic way to define the local y and z axes, i.e., how the section axes line up with the element. In two-dimensions, this is not an issue because the local z axis coincides with global Z, perpendicular to the XY plane of the model.

In OpenSees, the user must specify v_{xz}, a vector in the local xz plane of 3D frame elements. Then, the geometric transformation class computes the local y axis from v_{xz} \times x, followed by the local z axis from x \times y. Note that the v_{xz} vector can be the actual local z axis, but it cannot be equal to \pm x.

I’ve never liked this approach to specifying the orientation of 3D frame elements. I have a hard time figuring out a vector in the xz plane because I am not very good at geometry. But, even for people who are good at geometry, it is very easy to accidentally rotate the local y and z axes with this approach.

Consider the beam shown below. If we switch the I and J nodes but keep the same v_{xz}, the local y and z axes rotate by 180 degrees. This lack of invariance can be a problem when defining member loads along the local y axis to produce bending about the z axis, e.g., for beams in a 3D frame model.

Specifying a vector in the local xy plane, let’s call it v_{xy}, would resolve the lack of invariance for the local y axis. First compute local z from x \times v_{xy}, then compute local y from z \times x. The local z axis is flipped, but that is not too important when you’re applying member loads only along the local y axis.

But this post isn’t about member loads in 3D, nor is it about writing new constructors that take v_{xy} as input to the 3D geometric transformation classes. This post is about figuring out the v_{xz} input for OpenSees 3D frame elements without causing a migraine. So, if you want to define your elements such that global vertical is in the local xy plane, take an extra step in your input file and let Python calculate the local xz vector that OpenSees expects.

# Local x-axis from nodal coordinates
XYZI = ops.nodeCoord(ndI)
XYZJ = ops.nodeCoord(ndJ)
xaxis = np.subtract(XYZJ,XYZI)

# Vectors in the local x-y and x-z planes
vecxy = [0,1,0] # What you want (vecxy is global vertical)
vecxz = np.cross(xaxis,vecxy) # What OpenSees expects


In addition to elements that lie in a global horizontal plane, this approach will produce the correct local axes for inclined elements that are axisymmetric about the global vertical axis. This is good news for vectorphobes like me. Of course, elements whose local x axis aligns with global vertical remain a special case.

21 thoughts on “A Vector in the x-z Plane

  1. This is really insightful and clear!! OpenSees has been a challenge for me and some concepts are difficult to wrap my mind around but “the more that you read, the more things you will know. The more that you learn, the more places you’ll go” and there’s always more I could learn so thank you for sharing your wisdom!


  2. Thank you for a clear explanation.
    In that case, for Example 7 in OpenSees manual, shouldn’t the vecxz for girder elements be (-1 0 0) instead of (1 0 0) so that positive local y axis coincide with global vertical Y? The gravity load on girder elements were included with a -ve sign which implies its local y is coinciding with global vertical Y and it is only possible when vecxz is (-1 0 0). Please correct me if I am wrong.


      1. I tried posting the link here several times but somehow comment isn’t getting posted. Could you let me know an alternate way of sharing link with you?


    1. It depends on the I-J orientation of the girder elements. The local x-axis is directed from I to J. You can take all the lateral loads off and analyze for only gravity loads to see if equilibrium is satisfied.


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.