Torsion with Fiber Sections

I won’t blog about every pull request to OpenSees on GitHub, but I will blog about pull requests that could affect backward compatibility of user scripts. Pull request #142 is one such case. It affects how torsion is added to fiber sections in three-dimensional models.

The frame elements require torsional stiffness in order to prevent a local rigid body mode of spinning. The fibers in a uniaxial fiber section do not provide shear stress, so torsion is not one of the stress resultants. Torsion has to be added to the fiber section.

There are two methods to add torsion to a FiberSection3d object: 1) use the SectionAggregator to attach a UniaxialMaterial; 2) use the -GJ option in the fiber section definition.

# Method 1
section Fiber 3 {
   patch ...
   layer ...
uniaxialMaterial Elastic 5 $GJ ;# Doesn't have to be elastic
section Aggregator 1 5 T -section 3

# Method 2
section Fiber 1 -GJ $GJ {
   patch ...
   layer ...

Most people use Method 2 for which this pull request will not break backward compatibility. If you use Method 1, read on.

Years ago when I implemented Method 2, I put a bogus GJ value in to the FiberSection3d class to accommodate folks who might forget to use either Method 1 or Method 2. The force-based element would always have a full rank flexibility matrix to invert and the displacement-based element would have something to interpolate. No harm, no foul, right?

Wrong! This messed up folks who used Method 1, which apparently was a small group because it took years for anyone to notice this issue. It’s likely they struggled in silence with OpenSees convergence problems just like everyone else.

The issue with Method 1 is that the FiberSection3d object is created with an artificially high GJ value, giving a section stiffness matrix, {\bf k}_s, with the following topology:

{\bf k}_s = \left[ \begin{array}{cccc} X & X & X & 0 \\ X & X & X & 0 \\ X & X & X & 0 \\ 0 & 0 & 0 & 1e14 \end{array} \right]

The 3×3 block is the axial-flexural stiffness that comes from the uniaxial fibers. With Method 2, the absurdly large 1e14 is overwritten with the -GJ option and everything is fine. But, with Method 1, when the SectionAggregator adds the torsional UniaxialMaterial to the fiber section, the section stiffness matrix ends up with two torsional modes–one that’s junk and the other that the user requests:

{\bf k}_s = \left[ \begin{array}{ccccc} X & X & X & 0 & 0 \\ X & X & X & 0 & 0 \\ X & X & X & 0 & 0 \\ 0 & 0 & 0 & 1e14 & 0 \\ 0 & 0 & 0 & 0 & GJ \end{array} \right]

The frame elements in OpenSees are able to handle two torsional modes in the section–that’s not the problem. The problem is that the conditioning of the element stiffness matrix and/or stability of the element state determination could be poor due to the extremely stiff torsional response, leading to global convergence issues. What was I thinking?

This pull request fixes the issue by forcing the user to specify either a GJ value or a UniaxialMaterial for torsion when defining the fiber section.

# New Method 1
uniaxialMaterial Elastic 5 $GJ ;# Doesn't have to be elastic
section Fiber 1 -torsion 5 {
   patch ...

# Method 2 (same as before)
section Fiber 1 -GJ $GJ {
   patch ...
   layer ...

With the new Method 1, the FiberSection3d class is the aggregator, not the aggregated. Unfortunately, backwards compatibility is broken for the old Method 1. After this pull request, you will receive an error stating that there is no torsion in your fiber section. You have to use either the -GJ or the -torsion option.

The SectionAggregator did not go anywhere. You can still aggregate shear to a fiber section and create other aggregations of section response without any problems.

12 thoughts on “Torsion with Fiber Sections

  1. Hello, professor. Thank you for explaining the new way to handle torsional stiffness. I have some question about this topic.

    If my model is initialized by `model BasicBuilder -ndm 2 -ndf 3`, the result should be a 2D model and each joint contains only 3 DOFs corresponding to P, Mz and Vy? However, the OpenSees still asked me to provide the -GJ / -torsion value in fiber section command. Is this means the FiberSection3d always called nomatter the model is 2D or 3D?

    And in the framework design, why let the old method 1 command, `section Aggregator 1 5 T -section 3` as an example from above, add a new torsion mode rather than replace the existing torsional stiffness 1e14 since the $dof tag is T? Does this mean section aggregator will duplicate the DOF if the $dof tag issues the same material DOF already contained in the section referenced?

    Last question, the documentation says the -GJ argument is torsional stiffness. Is this means I should input G*J/L rath than G*J (torsional rigidity)?

    Sorry, I am new to OpenSees and not familier with cpp codes… Thank you for your replay.


    1. Hello HHangLi,

      The nodal DOFs do not correspond to P, Mz, and Vy, but rather to two translations and one rotation. OpenSees should only check for -GJ or -torsion for 3D models. Can you e-mail me an example script where you get this error in a 2D model?

      The old method 1 was incorrectly implemented. Without going into details, the solution with the new methods was easiest and cleanest.

      The -GJ argument is torsional stiffness, GJ, of the section. The elements will integrate and obtain torsional stiffness, GJ/L.



    2. Hello, I have a warning : no torsion specified …, as you. And my model is 2D. How did you fix that? Please, help.


  2. I guess you should not add the default GJ years ago. This is the problem. We are not responsible to make people do the correct, there can be mistakes (and this is their’s). If they use the default value in an analysis (not defining themselves-the default GJ, the results can also be wrong, this is not the correct GJ they should use, and maybe the calculations I made may be wrong, we should check)


Leave a Reply

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

You are commenting using your 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.