Manipulating the nodal equilibrium equations is necessary to enforce constraints between degrees of freedom (DOFs) at two or more nodes in a structural model. These multipoint constraints arise from assumptions of axial and flexural rigidity of frame elements, e.g., rigid diaphragms, and also between two nodes at the same location where some of the DOFs are the same, e.g., moment releases.
In addition to the Plain constraint handler, which only enforces singlepoint constraints like pin, roller, and fixed boundary conditions, as well as pressure constraints in the PFEM, OpenSees has three multipoint constraint handling methods: Penalty, Lagrange, and Transformation.
The “Cook book” describes the theory behind these methods and how they handle constraints at the global level. Their implementation in OpenSees is a little different, where FE_Element and DOF_Group objects enforce the constraints locally among affected DOFs.
An unfortunate side effect of enforcing multipoint constraints is some convergence tests and equation solvers will not get the job done if you use the Penalty or Lagrange method. It’s also possible for the Transformation method to give incorrect results if a nodal DOF is involved in more than one constraint, even when one of the constraints is singlepoint.
OpenSees doesn’t warn you that you’re doing something funky with constraint handlers. Like wearing brown socks with black shoes, you’re just supposed to know that it doesn’t work. I will demonstrate where you can go wrong with this simple example.
Half of the span is flexible while the other half is rigid, using the rigidLink command in OpenSees with node 2 retained and node 3 constrained (rigidLink beam 2 3
). Due to axial and flexural rigidity, nodes 2 and 3 should have the same horizontal displacement and the same rotation. The difference in vertical displacement between nodes 2 and 3 should be equal to the rotation times the rigid length.
Penalty Method
The penalty method adds artificial springs of high stiffness to the nodal equilibrium equations in order to enforce the constraints. The spring stiffnesses, or penalty numbers, should be large enough to enforce the constraints, but not so large as to cause illconditioning of the system of equations.
Although you can use different penalty numbers for each constraint, OpenSees takes only two penalty numbers: one for all the singlepoint constraints and one for all the multipoint constraints. Penalty numbers about three or four orders of magnitude higher than some characteristic stiffness of the model usually work pretty well. For the penalty numbers in this example, we’ll use where =240 in is the span length.
Because small changes in displacement can lead to large changes in force with very stiff springs, using the NormUnbalance convergence test with penalty constraints is illadvised. As shown below, the convergence test gets stuck even though the norm of the displacement increment is very small.
The equilibrium iteration will converge if we use the NormDispIncr convergence test. You can verify that the nodal displacements satisfy the constraints imposed by the rigid beam.
Lagrange Multipliers
With the Lagrange constraint handler, constraint equations are added to the system of nodal equilibrium equations with Lagrange multipliers as the additional unknowns. Because the single and multipoint constraints are handled simultaneously with Lagrange multipliers, some gymnastics are required to make things work.
Because the constraint equations can be scaled arbitrarily, there are scale factors, and , required for Lagrange multipliers. The default values of 1.0 will not work–you need to make these factors large like penalty numbers. Like in the Penalty method, we’ll use for the scale factors.
Along with these constraint equations come zeros along the diagonal of the simultaneous system of nodal equilibrium and nodal constraint equations. This is a problem for several solvers available in OpenSees, including the default ProfileSPD which fails due to zeros on the diagonal.
To get around this, you will need to use a general solver like UmfPack, FullGeneral, or SparseGeneral piv with Lagrange multipliers. As shown below, compatible nodal displacements are obtained.
Transformation Method
The Transformation method uses static condensation to enforce multipoint constraints. There are no issues with this approach in terms of convergence tests or equation solvers. However, the Transformation method can become confused, or “noninvariant”, when there are DOFs involved in more than one constraint. For this example, the Transformation method gives an incompatible solution without any analysis errors or warnings.
There is a terse summary of the issue on the OpenSees wikipedia page for Transformation constraints: “If multiple nodes are constrained, make sure that the retained node is not constrained in any other constraint.” This basically means don’t daisy chain the constraints like you would power strips.
For the beam example of this post, the vertical DOF at node 3 is retained in the single point constraint. This roller is a master of none, but a master nonetheless, so it cannot be a retained node in the rigidLink command. If we switch the retained and constrained nodes in the rigidLink command (rigidLink beam 3 2
), the results make sense.
Regardless of which constraint handling method you use, always check your output when using multipoint constraints. Even with compatible nodal displacements, the reactions can appear to violate equilibrium, but I’ll save that for another post.
hey,you wanna make a video for my channel about this post?it’s really because I had convered constraints already but you go deeper into it. s
LikeLike
It might be a while. After writing this post, I want nothing to do with constraint handlers 🙂
LikeLike
Great post!
LikeLike
Dear P. D. ,
Thanks again for discussing all the options. As you know a leaning column with gravity loads is linked to the frame by truss elements to simulate PDelta effects.
Why don’t they use equalDOF instead of truss elements? Is this related to constraint handling?
https://opensees.berkeley.edu/wiki/index.php/Pushover_Analysis_of_2Story_Moment_Frame
LikeLike
Hello Adnan,
equalDOF could be used, but the truss elements give some physical distance when viewing the model.
PD
LikeLike
Dear P. D.,
Many thanks.
🙏🙏🙏
LikeLike
Dear Dr. P. D. ,
Thanks for giving this nice and helpful post! I often find myself easily getting confused about the situations in which I can use the transformation method and would usually use the penalty method which would give me convergence problems sometimes… In the example you give, it seems the transformation method can be used for DOFs that are involved in more than one constraint right? However, I see one post by Frank on the OpenSees message board explaining that “if a node is fixed or constrained to move in a certain way, constrain it using the fix or sp commands and do not use the equalDOF command as that is a constraint following a constraint” (https://opensees.berkeley.edu/community/viewtopic.php?f=2&t=32112&p=83851&hilit=equaldof+multiple+nodes#p83851).
The equalDOF and rigidlink are two different commands but they are both for mp constraints. I don’t quite understand why the transformation method can be used in your example but cannot be used with equalDOF. Could you explain more on this? Is it correct to use the transformation method if one node is pinned connected to the ground while being a retained node for another node for moment release?
I got this question because I have a 3D building model with 2story basements in which the perimeter column nodes are supposed to be connected to the ground while there are beams with end moment released connected to the column nodes. Is it appropriate to use the transformation method in this model? I tried to connect the column node to the ground (x and y DOFs are fixed using: fix $colNodeTag 1 2) while using the column nodes as retained nodes (equalDOF $colNodeTag $beamNodeTag 1 2 3 4) and the modal results seems correct. The following is a sketch (sorry I cannot upload images..):
column
+


ground Δ–o————–+
 beam

+
column
Much appreciate it if you could provide any input!!
Regards,
Junfei
LikeLike
Hello Junfei,
I think Frank is referring to nodes to which you want to impose a displacement history when he wrote “if a node is fixed or constrained to move in a certain way, constrain it using the fix or sp commands and do not use the equalDOF command as that is a constraint following a constraint”. For example, a cyclic displacement history on a column experiment.
PD
LikeLike
Dear Dr. P. D. ,
Thanks a lot for the prompt reply! In that post, Frank gave an example about the usage of transformation on the constraints in which the nodes are not imposed displacement histories:
the correct set of constraints for this model are:
fix 1 0 1 1 0 0 0;
fix 3 0 1 1 0 0 0;
fix 4 1 1 1 1 1 1;
equalDOF 1 2 1
equalDOF 1 3 1
fix 2 0 1 0 0 0 0
the original case
fix 1 0 1 1 0 0 0;
fix 3 0 1 1 0 0 0;
fix 4 1 1 1 1 1 1;
equalDOF 1 2 1
equalDOF 1 3 1
equalDOF 4 2 2
violates (a) – 2 is asked to follow 4 in the 2 dirn, but 4 in the 2 dirn already has a constraint.
The constraint conditions (between node 4 and node 2) in that example seems similar to the building case problem I have so I am still not sure whether I can use it or not.
Regards,
Junfei
LikeLike
Hello Junfei,
The issue may be specific to your model. Getting in to details here in the comments section is not ideal. Consider the OpenSees message board or, if you would like, you can schedule a oneonone consultation: https://www.silviasbrainery.com/oneononetraining
PD
LikeLike