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, , OpenSees currently has in memory.

Note that the `printA`

function only works with the `FullGeneral`

system of equations, which stores the entire 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 matrix to the standard output stream, which is useless for any model with more than two DOFs (). 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 , , and from your model. You can get by first doing a static analysis, then calling `printA`

. Easy. And, I recently learned that you can get by calling `printA`

after switching to the `NewmarkExplicit`

integrator with . Also easy. If you are using Rayleigh damping where is a linear combination of and , 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 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 or small number of damping elements when assembling .

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.

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

Hola Gustavo,

Thanks for the tip! Let me know how it goes.

PD

LikeLike

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

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

This is a great development! Thank you

LikeLiked by 1 person

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

Thanks, Yan!

It should be in OpenSeesPy, but not yet documented on the page.

PD

LikeLike

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

Thanks! Whether or not you see a warning message depends on the order in which you specify the analysis commands.

LikeLike

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

You can use the nodeDOFs command to get the equation numbers.

LikeLike

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

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

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

Thank you! It’s nice to know the posts are helpful.

LikeLike

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

The damping matrix is never formed explicitly with modal damping. The damping forces are added directly to the right-hand side vector.

LikeLike

Thank you very much for the clarification.

LikeLiked by 1 person

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

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

LikeLiked by 1 person

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

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

It’s from the Appendix of Chapter 14 in Chopra, 5th edition

LikeLike

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

Without any context, that question cannot be answered. I recommend you post more details on the OpenSees message board or Facebook group.

LikeLike

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

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