Gimme All Your Damping, All Your Mass and Stiffness Too

Michael H. Scott Structural Dynamics May 17, 2020July 25, 2022 5 Minutes

Just because OpenSees is open source does not mean it is a fully transparent box. This is mostly because documentation has lagged behind development. So, pessimists would say the box is semi-opaque while optimists would characterize it as semi-transparent. But a few parts of OpenSees are definitely housed in an opaque box.

Take, for instance, the stiffness matrix. We received many requests for functionality to extract the stiffness matrix for post-processing and offline calculations, e.g., in MATLAB. As a result, the printA function was added a few years ago. This function returns the left-hand side matrix in whatever linear system of equations, ${\bf A}{\bf x}={\bf b}$ , OpenSees currently has in memory.

Note that the printA function only works with the FullGeneral system of equations, which stores the entire $N \times N$ matrix. Getting the non-zeros out of sparse matrix storage and filling in zeros where needed is just not worth the effort.

With no input arguments, printA prints the ${\bf A}$ matrix to the standard output stream, which is useless for any model with more than two DOFs ( $N > 2$ ). There is, however, an option to write the matrix to a file with printA -file filename. You can then load this file into MATLAB. In OpenSeesPy, there is an option to return the matrix as a list to the interpreter, printA('-ret'). More on this later.

For a static analysis, printA gives the tangent stiffness matrix. For a dynamic analysis, printA gives the effective tangent stiffness matrix, which is not physically meaningful because it is a linear combination of the mass, damping, and static stiffness matrices with scalar coefficients dictated by the integrator and the time step.

Let’s suppose you’re doing a dynamic analysis and want to get ${\bf M}$ , ${\bf C}$ , and ${\bf K}$ from your model. You can get ${\bf K}$ by first doing a static analysis, then calling printA. Easy. And, I recently learned that you can get ${\bf M}$ by calling printA after switching to the NewmarkExplicit integrator with $\gamma=0$ . Also easy. If you are using Rayleigh damping where ${\bf C}$ is a linear combination of ${\bf M}$ and ${\bf K}$ , you’re done.

But what if your model has viscous dampers and you want to get the non-classical damping matrix? What if you want to do state space calculations offline because OpenSees does not have state space functionality? You’ll be SOL on the damping matrix. As far as I can tell, there’s no integrator available that you can trick into forming only the damping matrix like you can with NewmarkExplicit and the mass matrix.

So, after trying some arduous and non-scalable approaches to forming ${\bf C}$ with imposed velocities and single point constraints, I realized I could just implement a new integrator to trick OpenSees into giving me what I want. This new integrator assembles any linear combination of mass, damping, and stiffness (tangent and initial) that you tell it. Then, you can grab that matrix with printA. I named it GimmeMCK (see PR #343) because better names just didn’t come to mind.

Python
ops.integrator('GimmeMCK', m, c, kt, ki=0.0) Tcl
integrator GimmeMCK $m $c $kt <$ki> m = factor applied to mass matrix c = factor applied to damping matrix kt = factor applied to tangent stiffness matrix ki = factor applied to initial stiffness matrix (optional, default=0.0)

Assembles A = m*M + c*C + kt*KT + ki*KI

Because you don’t want to perform an actual analysis with this integrator, I removed the functionality to advance time in the domain and to update displacement, velocity, and acceleration like you see in the proper dynamic integrators. Although, maybe one would want this functionality to play around with new integrators without having to touch the source code. Let me know if that functionality appeals to you.

With your model defined, at any time you can switch to the GimmeMCK integrator, dump out the matrices you want, then switch back to a real dynamic integrator and proceed as if nothing happened. Don’t worry if you see analysis failed warnings because the assembled matrix is singular, e.g., massless DOFs when assembling ${\bf M}$ or small number of damping elements when assembling ${\bf C}$ .

Below is a synopsis of using the GimmeMCK integrator to get the mass, stiffness, and damping matrices from an OpenSees model defined in Python.

import openseespy.opensees as ops
import numpy as np
import scipy.linalg as slin

#
# Define your model
#

ops.wipeAnalysis()
ops.system('FullGeneral')
ops.analysis('Transient')

# Mass
ops.integrator('GimmeMCK',1.0,0.0,0.0)
ops.analyze(1,0.0)

# Number of equations in the model
N = ops.systemSize() # Has to be done after analyze

M = ops.printA('-ret') # Or use ops.printA('-file','M.out')
M = np.array(M) # Convert the list to an array
M.shape = (N,N) # Make the array an NxN matrix

# Stiffness
ops.integrator('GimmeMCK',0.0,0.0,1.0)
ops.analyze(1,0.0)
K = ops.printA('-ret')
K = np.array(K)
K.shape = (N,N)

# Damping
ops.integrator('GimmeMCK',0.0,1.0,0.0)
ops.analyze(1,0.0)
C = ops.printA('-ret')
C = np.array(C)
C.shape = (N,N)

Continue with the following code if you want to perform state space analysis on the model. You’ll notice code to separate the DOFs with mass from those without mass using the nodeDOFs and nodeMass commands. This separation is necessary for static condensation prior to the state space analysis. You may find the node utility commands useful for other stuff too.

# Determine number of DOFs with mass
massDOFs = []
for nd in ops.getNodeTags():
    for j in range(NDF): # NDF is number of DOFs/node
        if ops.nodeMass(nd,j+1) > 0.0:
            massDOFs.append(ops.nodeDOFs(nd)[j])

# Number of DOFs with mass
Nmass = len(massDOFs)

# DOFs without mass
masslessDOFs = np.setdiff1d(range(N),massDOFs)
Nmassless = len(masslessDOFs)

# Form matrices for D*x = -lam*B*x
B = np.zeros((2*Nmass,2*Nmass)) # = [ 0 M; M C]
D = np.zeros((2*Nmass,2*Nmass)) # = [-M 0; 0 K]

# Mass
B[:Nmass,:][:,Nmass:2*Nmass] =  M[massDOFs,:][:,massDOFs]
B[Nmass:2*Nmass,:][:,:Nmass] =  M[massDOFs,:][:,massDOFs]
D[:Nmass,:][:,:Nmass]        = -M[massDOFs,:][:,massDOFs]

# Damping
B[Nmass:2*Nmass,:][:,Nmass:2*Nmass] = C[massDOFs,:][:,massDOFs]

# Static condensation
Kmm = K[massDOFs,:][:,massDOFs];     Kmn = K[massDOFs,:][:,masslessDOFs]
Knm = K[masslessDOFs,:][:,massDOFs]; Knn = K[masslessDOFs,:][:,masslessDOFs]
# Kc = Kmm - Kmn*inv(Knn)*Knm
if Nmassless > 0:
    Kc = Kmm - np.dot(Kmn,np.linalg.solve(Knn,Knm))
else:
    Kc = K

# Stiffness at DOFs with mass
D[Nmass:2*Nmass,:][:,Nmass:2*Nmass] = Kc

# State space eigenvalue analysis
[lam,x] = slin.eig(D,-B)

Let me know if you run into any problems getting the matrices out of OpenSees.

The title for this post was inspired by ZZ Top’s “Gimme All Your Lovin'”, which saw heavy play on MTV, back when MTV played music videos.

Published by Michael H. Scott

I have been involved in the development, maintenance, and growth of OpenSees since its early days. I am interested in learning Python and improving my academic writing. View all posts by Michael H. Scott

Published May 17, 2020July 25, 2022

39 thoughts on “Gimme All Your Damping, All Your Mass and Stiffness Too”

Gustavo Araujo says:

May 17, 2020 at 12:35 pm

PD,

This is awesome! Just what I needed to perform a response spectrum analysis!

I am definitely going to try it and let you know!

As an extra comment, I just would say that saving a matrix to a text file is probably not the most efficient way. I am working in a model whose system size is 3000 and I found that saving it to a binary file using numpy.save() was the best approach.

LikeLiked by 1 person

Reply
1. Positive Definite says:
  
  May 17, 2020 at 12:38 pm
  
  Hola Gustavo,
  Thanks for the tip! Let me know how it goes.
  PD
  
  LikeLike
  
  Reply
Mary says:

July 25, 2020 at 5:47 am

Hello PD,

I have a question regarding the element’s stiffness matrix. Is there a way to obtain the stiffness matrix of each element of a structure modeled in OpenSees?

Thank you.

LikeLike

Reply
1. Positive Definite says:
  
  July 25, 2020 at 6:57 am
  
  Hello Mary,
  Some of the frame elements have a recorder option for their basic stiffness matrix. Most elements do not have the option though.
  PD
  
  LikeLike
  
  Reply
Volkan Özsaraç says:

August 17, 2020 at 1:22 am

This is a great development! Thank you

LikeLiked by 1 person

Reply
Pingback: A Marathon, Not a Sprint – Portwood Digital
Pingback: Closing the Loop on Direct Assembly – Portwood Digital
Yan says:

October 29, 2020 at 3:06 am

Good job! Has this integrator “‘GimmeMCK'” been included in the release of OpenSeesPY? I can’t find this interpreter on the home page of Openseespy. Thank you!

LikeLike

Reply
1. Positive Definite says:
  
  October 29, 2020 at 6:27 am
  
  Thanks, Yan!
  It should be in OpenSeesPy, but not yet documented on the page.
  PD
  
  LikeLike
  
  Reply
Xinyue says:

December 15, 2020 at 2:29 pm

I just tried this command and it works well. Thanks for this great development. I found one thing confusing though. In the synopsis you provided above, the numberer isn’t specifed. In this case, from the error message I found OpenSees assumes the default RCM numberer. However, even if I specifeied the numberer as ‘Plain’, error message still prints ‘RCM default will be used’, which is confusing. In reality, Plain numberer has been used, because [K] given by Plain numberer is diffrent from the previous [K] given by RCM.
Please correct me if I am wrong. Thanks again!

LikeLike

Reply
1. Positive Definite says:
  
  December 15, 2020 at 5:18 pm
  
  Thanks! Whether or not you see a warning message depends on the order in which you specify the analysis commands.
  
  LikeLike
  
  Reply
Pingback: Right Under Your Nose – Portwood Digital
Pingback: Building Blocks – Portwood Digital
locallog says:

October 29, 2021 at 6:50 am

I wanted to use this function to calculate the energy of the system.. say for viscous damping, something along the lines of the damping matrix *velocity vector * nodal displacement for a given time instant in the analysis. One problem that I’m trying to figure out is which DOF maps to which velocity vectors /displacement vectors since it seems that equalDOF (and maybe other constraints), changes the size of the MCK matrices. It’s easy enough to get the velocity/disp/acceleration vectors of the system (using recorders on every node), but I wish I could do something to map the MCK to those nodal dofs so I could perform energy calcs.

LikeLike

Reply
1. Positive Definite says:
  
  October 29, 2021 at 8:29 am
  
  You can use the nodeDOFs command to get the equation numbers.
  
  LikeLike
  
  Reply
  1. Louis Lin says:
    
    October 30, 2021 at 11:13 am
    
    Ah- That’s perfect!
    
    Thank you Prof. McKenna.
    
    I briefly saw energy recorders mentioned in a powerpoint somewhere on the web- will those be implemented in the future?
    
    LikeLike
  2. Positive Definite says:
    
    October 30, 2021 at 12:30 pm
    
    Ha! I’m flattered that you think Frank writes this blog 🙂
    Regarding your recorder question, you should create a GitHub issue to see if this feature can be added.
    
    LikeLike
Ben Moerman says:

February 1, 2022 at 1:56 pm

Just wanted to drop a note of appreciation and thanks for your blog. This and several other posts have clarified some very niche topics in Opensees for me. Also, the title on this post is brilliant. Thanks Dr. Scott.

LikeLiked by 1 person

Reply
1. Michael H. Scott says:
  
  February 1, 2022 at 4:53 pm
  
  Thank you! It’s nice to know the posts are helpful.
  
  LikeLike
  
  Reply
Akshay Somkuwar says:

March 31, 2022 at 5:00 pm

I have defined modal damping with damping ratio of 0.02 in first mode. My model has only one storey and 1 bay. But the extracted damping matrix has 0 as its elements. What could be the problem? Does the integrator only works with Rayleigh damping?

LikeLike

Reply
1. Michael H. Scott says:
  
  April 1, 2022 at 9:46 am
  
  The damping matrix is never formed explicitly with modal damping. The damping forces are added directly to the right-hand side vector.
  
  LikeLike
  
  Reply
  1. Akshay Somkuwar says:
    
    April 2, 2022 at 5:02 am
    
    Thank you very much for the clarification.
    
    LikeLiked by 1 person
2. Michael H. Scott says:
  
  April 2, 2022 at 8:34 pm
  
  I’m sorry, it turns out a necessary function wasn’t defined in GimmeMCK. It’s there now and should return the modal damping matrix.
  https://github.com/OpenSees/OpenSees/commit/d2250047f74ab47fe7136e22769fcfb2e8b7c5a3
  
  LikeLike
  
  Reply
  1. Akshay Somkuwar says:
    
    April 6, 2022 at 6:06 am
    
    Prof. Scott Thank you very much for updating the integrator. Extracted modal damping matrix matches with manual calculation.
    
    LikeLiked by 1 person
Pingback: Gimme All Your Modal Damping – Portwood Digital
Danny says:

April 22, 2022 at 7:27 am

Dear Prof. Scott, thank you for your post about GImmeMCK. It’s a wonderful function in OpenSees and I have been extensively using it.

I was quite curious about your approach to the state space analysis because the method used in this article is alien to me. AFAIK, State Space requires the K and M only. And usually the A matrix is just = [zeros ones; -k/m -c/m]. Does your D and -B represent -k/m and -c/m, respectively? My intuition about the matrix size said it not (because the A matrix in state space would only be 30×30).

Thank you very much for your kind attention.

LikeLike

Reply
1. Danny says:
  
  April 22, 2022 at 7:30 am
  
  Or, to rephrase my question in a simpler term, what kind of state space formulation is [ 0 M; M C] [-M 0; 0 K]?
  
  Thanks again for your attention.
  
  LikeLike
  
  Reply
  1. Michael H. Scott says:
    
    April 22, 2022 at 9:35 am
    
    It’s from the Appendix of Chapter 14 in Chopra, 5th edition
    
    LikeLike
ZHONG says:

May 8, 2022 at 7:19 am

Dear Prof. Scott, I learned a lot from GImmeMCK. Thank you so much! I find a question when I am using the GImmeMCK: Why C≠(alphaM *M+betaKinit*K)?

LikeLike

Reply
1. Michael H. Scott says:
  
  May 8, 2022 at 7:50 am
  
  Without any context, that question cannot be answered. I recommend you post more details on the OpenSees message board or Facebook group.
  
  LikeLike
  
  Reply
  1. ZHONG says:
    
    May 8, 2022 at 7:35 pm
    
    Dear Prof. Scott, I uploaded more details and source files on Facebook. In a two DOF rigid shear frame model, the Rayleigh damping matrix C calculated by ‘GimmeMCK’ and the result calculated by ‘M*alphaM+K*betaKinit’ are the same. However, in a two DOF rigid shear frame model with diagonal braces. I’m very confused about this. Thank you very much!
    
    LikeLike
ZHONG says:

May 10, 2022 at 12:05 am

Thank you very much for your answer in the Facebook group! Now the result is perfect! Can I ask you two more questions: (1) Is the order of the degrees of freedom of the mass matrix obtained by GimmeMCK consistent with the order of getNodeTags0? (2) Does the node mass obtained by the nodeMass0 command include all masses (including the node mass converted from the consistent mass), or only those created with the Mass command?

LikeLike

Reply
Danny says:

June 24, 2022 at 12:32 am

Hi Prof. Scott,

I am doing an analysis where I applied rigid diaphragm. Because of the rigid diaphragm, the system size is no longer number of node * DOF, thus I am facing some problem with the static condensation code to remove the massless node using the above code. I don’t know how it really work, but I guess OpenSees internal probably has done some static condensation to create the rigid diaphragm.

(Note: it’s a 2D problem so rigid diaphragm may not be exactly the correct term, pardon my ignorance).

I used this code as an alternative to the first 12 lines of your state-space matrix construction code.

# Number of DOFs with mass
massDOFs = np.where(np.diag(M) != 0)[0]
Nmass = len(massDOFs)

# DOFs without mass
masslessDOFs = np.where(np.diag(M) == 0)[0]
Nmassless = len(masslessDOFs)

Do you have any comment on this? For your kind attention, thank you.

LikeLike

Reply
1. Michael H. Scott says:
  
  June 24, 2022 at 3:34 pm
  
  I used systemSize in the code, not Nnode*Ndof.
  
  LikeLike
  
  Reply
  1. Danny says:
    
    June 25, 2022 at 9:20 am
    
    It is for this part
    
    # Determine number of DOFs with mass
    massDOFs = []
    for nd in ops.getNodeTags():
    for j in range(NDF): # NDF is number of DOFs/node
    if ops.nodeMass(nd,j+1) > 0.0:
    massDOFs.append(ops.nodeDOFs(nd)[j])
    
    For the M,C,K, yes it is determined by the system size. But for the massDOFs, isn’t the loop above equals to Nnode*Ndof? Pardon me if I am reading it wrong.
    
    Thank you for the attention.
    
    LikeLike
Pingback: Top 5 Posts – Portwood Digital
Berkan says:

March 14, 2023 at 11:17 am

Hi Prof. Scott,
In openseespy i try to get mass, stiffness and damping matrices for mdof lumped model which have isolator in midstory. GimmeMCK does not give me right damping matrix but it gives right mass and stiffness matrices. How can i get right damping matrix?
Thanks in advance

LikeLike

Reply
1. Michael H. Scott says:
  
  March 14, 2023 at 11:56 am
  
  Please post your script and question on the OpenSees message board or Facebook group. Also, generate a MWE where you know what the “right” damping matrix is.
  (I am removing the long script your posted with your comment)
  
  LikeLike
  
  Reply
  1. Berkan says:
    
    March 14, 2023 at 2:34 pm
    
    i did
    
    LikeLike