Gimme All Your Damping, All Your Mass and Stiffness Too

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.

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

  1. 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.

    Liked by 1 person

  2. 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.

    Like

  3. 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!

    Like

  4. 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!

    Like

  5. 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.

    Like

      1. 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?

        Like

  6. 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.

    Liked by 1 person

  7. 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?

    Like

      1. Prof. Scott Thank you very much for updating the integrator. Extracted modal damping matrix matches with manual calculation.

        Liked by 1 person

  8. 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.

    Like

    1. 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.

      Like

  9. 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)?

    Like

      1. 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!

        Like

  10. 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?

    Like

  11. 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.

    Like

      1. 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.

        Like

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.