MDOF

(Multi-Degree of Freedom) Application

1. Tool Audience (Users):

1) Students taking courses in structural dynamics, earthquake or wind engineering.
2) Researchers/Practitioners trying to understand a building response to a Natural
Hazard.

2. Tool Purpose:

This educational application will allow the user to explore the effects of different building
parameters on the time history response of a building subjected to earthquake, wind or
other loadings that generate a transient response of the structure, i.e. time varying
response.

The building itself is to be represented by a shear building model: an idealization of a
structure in which the mass is lumped at the floor levels and the beams are assumed
infinitely stiff in flexure and axially inextensible, and the columns are axially inextensible.
The user will input the floor weights and story properties (stiffness, yield strength,
hardening ratio) of the stories, and a damping ratio for the elastic modes of vibration.

The user will quickly be able to explore the effect of changing weight, height, and stiffness
on the time history response. In addition, nonlinear effects due to P-Delta effects and soft
story mechanisms will also be able to be studied.

3. Requirements:

A user group consisting of Professors teaching courses in dynamics, wind or earthquake
engineering and graduate students who have previously taken such courses was convened
following the initial NSF site visit and the recommendation to generate requirements for
SimCenter tools. This group consists of the following:
• SimCenter members: Prof. Steve Mahin, Dr. Andreas Schellenberg, Frank McKenna
• Non-SimCenter: Prof. Michael Scott (Oregon State University), Prof. Kevin Mackie
(University of Central Florida), Dr. Hartanto Wibowo (Iowa State University), Mr. Aditya
Pandey (UC Berkeley) and Mr. Ben Shao (UC Berkeley).

Dr McKenna conversed individually and in group settings with members of this group. The
following are the main user requirements identified by the group:

# Description Priority Version
User able to modify properties of building and see effect on
response:
1.a a) Number of Floors M 1.0
1.b b) Building Height and Weight M 1.0
1.c c) Stiffness and Yield properties of Stories M 1.0
1.d d) Floor Weights M 1.0
1.e e) Modal Damping Ratios D 1.0
2 User able to turn on/off the inclusion of PDelta effects D 1.0

3 User able to save current building properties into a file and D 1.0
 subsequently load at any later instance in time.
User able to view how response parameters change with time:
a) Plot of Floor displacements and story shear forces versus
4.a time. M 1.0
b) Plot of Shear Forces versus Interstory Disp
4.b M 1.0
User able to subject building to earthquake response:
5.a a) User able to select from a range of ground motions stored M
as files on user system.
5.b b) User able to scale motion magnitude. D

6 User able to subject building to harmonic excitation being able to D
adjust magnitude and frequency of the harmonic
User able to subject the building to wind loading
7.a a) Wind loads from file on user system. D
7.b b) Wind loads from CFD simulation. P

User able to subject the building to wave loading
8.a a) Wave loads from file on user system. D
8.b b) Wave load from CFD or PFEM simulation P
9 User able to select from various base isolation models to see effect P
of base isolation on response of building
10 User able to select from various base isolation models to see effect O
of base isolation on response of building.
User able to able to view modal quantities for Elastic response: P
a) Modal participation
11.a b) Modal mass
11.b c) Modal responses contributions to total response
11.c
12 User able to add floor and interstory damper systems to building to O
see effects of dampers on response of building
13 Visibly highlight current location in history plots (disp, story force, D
acceleration)

14 Ability to plot response of multiple buildings P
15 Ability to compare current results with previous result D
M=Mandatory, D=Desirable, O=Optional, P=Possible Future

4. User Workflow:

A high level description of user workflow, as
shown in figure, would be user starting the tool
and, until the user exits, they would interact with
the input panel to update input motion and
building properties and instantly view the
changes these modifications make in the output
panel. The user would go back to input panel and
make subsequent changes to see the effect on
response of these changes. At anytime before
exiting the tool, the user will have the option to
save the current settings.

As shown, the input panel will allow user to select from a set of existing ground
motions or add new ones from the users file system. The input panel will allow user
to modify building properties, i.e. number of stories, buildings height and weight,
and story stiffness’s. In addition the user will be able to load previously saved
buildings.

The output panel will allow user to view the overall building response, and will
allow user to view individual floor and story time history responses. These
responses are updated automatically as the user makes changes in the input panel.

5. System Specification:

The system specification defining the operation of the system is maintained in a
spreadsheet that is available to the programmers and is maintained on a SimCenter
box account. It will be available to users through the DesignSafe web page devoted
to this site when version 1.0 is released. The spreadsheet provides detailed
functionality of every button, entry fields, pull-down menus, available to the user
and their actions:

6. Schedule:

Version Release Requirements
1.0 Sep 2017 1.a, 1.b, 1.c, 1.d, 2, 3, 4.a, 4.b, 5.a
1.1 Dec 2017 5.b, 6.a, 7.a, 8.a
2.0 T.B.D. 7.b, 8.b, 9, 10, 11.a, 11.b, 11.c,12

7. Milestones:
• March 2017, Prototype V0.1 released to leadership and code placed into
Github.
 • June 2017, Prototype V0.2 released to leadership and REU students.
• July 2017: Alpha version of V1.0 released to user group and certain NHERI
Summer institute participants.
Sep 2017: Initial release of V1.0
•

8. Communications among team members while tool under development:

1. Weekly meeting between Designer and Programmer while tool under active
development.
2. Weekly show and tell with other SimCenter programmers to elicit feedback
while tool under active development.
3. Meeting between Programmer and those testing tool to go over bugs
encountered during testing and develop testing protocol.
4. Before release of tool, provide tool to user group members for testing and
additional feedback.

9. Staffing with Required Expertize:

Tool development requires user interface design, user interface programming, finite
element programming for earthquake simulation and computational fluid dynamics
for wind/water-structure coupling if necessary.

• UI Design: Max Rutman, Andreas Schellenberg
• UI Programming/FE Programming: Frank McKenna.
• CFD Programming (if necessary in future): Michael Motley, Peter McKenzie
• Tool Testing: John Lowe, SimCenter REU students (Danielle Charleston and
Tiffany La), and User group members.
• V&V: Frank McKenna and John Lowe.

10. Source Code:

This source code for the tool is released under the 2-clause BSD License, commonly
called the FreeBSD license. It is available for download from the tools GitHub
repository: https://github.com/NHERI-SimCenter/MDOF

11. Documentation:

Documentation for this tool will consist of the following:
1) This document
2) Short video documenting tool use.
3) Spreadsheet with System functionality.
4) Verification examples input files and corresponding Matlab .m files (purpose of
which is discussed in next section).

This document and Items (1) through (3) are available at the tool website
(https://simcenter.designsafe-ci.org/learning-tools/multiple-degrees-freedom-
application/) . Items in (4) is available in the examples directory on the tools Github
page. (https://github.com/NHERI-SimCenter/MDOF)

12. Verification:

12.1 Theory:

A simplified model of a building is obtained
by assuming that all the building weight is
lumped at the floor levels, that the floor
beams are rigid, and columns are axially
inextensible. Together these assumptions
allow us to generate a “shear-beam” or stick
model of the building.


The model consists of a set of nodal points, one at each floor level, and a set of
interconnecting elements representing the columns. The model is fully described by
the floor weights, Wi, at the nodal points and by the element properties [Ki, FYi and
bi]: where Ki is the sum of the column stiffnesses, FYi the yield strength of the story,
and b the kinematic hardening ratio. At any time t the equation of motion is:
𝑴𝒖(t) + 𝑪𝒖(t) + 𝑭𝒔 (𝒖(t)) = 𝑷(t)
A transient analysis of the structure now simply involves satisfying the equilibrium
equation at the nodal points. A numerical approach solves the equations at a
number of discrete time intervals, 𝑡 = 𝑖 ∗ ∆𝒕, apart:
𝑴𝒖𝒊 + 𝑪𝒖𝒊 + 𝑭𝒔 (𝒖𝒊 ) = 𝑷𝒊
For solving the equations the application uses the implicit Newmark constant
average acceleration scheme. A consequence of this is that the nodal responses for
time 𝒕 + ∆𝒕 are determined using equilibrium at the same time step. The Newmark
scheme provides difference relations that allow the velocities 𝒖𝒊!𝟏 and accelerations
𝒖𝒊!𝟏 to be computed, once the displacements 𝒖𝒊!𝟏 = 𝒖𝒊 + ∆𝒖𝒊 are known.
Expressing the equilibrium equation at this time step and using these difference
relations results in a set of nonlinear algebraic equations in the nodal displacements
𝒖𝒊!𝟏
𝟎 = 𝑹( 𝒖𝒊!𝟏 ) = 𝑷𝒊!𝟏 − 𝑭𝑺 (𝒖𝒊!𝟏 ) − 𝑴𝒖𝒊!𝟏 ( 𝒖𝒊!𝟏 ) − 𝑪𝒖𝒊!𝟏 ( 𝒖𝒊!𝟏 )

The application uses a Newton-Raphson iterative solution procedure to solve this

nonlinear algebraic equation. This scheme results in a linearized model of the
nonlinear equation at the current state for each iteration j=1, 2, … :
𝒋 𝒋 𝒋 𝒋
(𝒂𝟏 𝑴 + 𝒂𝟐 𝑪 + 𝒂𝟑 𝑲𝒊!𝟏 )∆𝒖𝒋 = 𝑷𝒊!𝟏 − 𝑭𝑺 (𝒖𝒊!𝟏 ) − 𝑴𝒖𝒊!𝟏 − 𝑪𝒖𝒊!𝟏

where the constants 𝑎!, 𝑎! , and 𝑎! are constants and for a shear-building the Mass
matrix, M, and stiffness matrix, K, are as defined below:



Damping for this tool is provided assuming a Modal Damping assumption. In modal
damping the C Matrix is defined as shown below:

Earthquake Excitation:
The approach used in this tool to impose earthquake loading on a structure is to use
a uniform excitation approach, which results in the following equation of motion:
𝑴𝒖(t) + 𝑪𝒖(t) + 𝑭𝒔 (𝒖(t)) = −𝑴𝒖𝒈 (t)

It should be noted, that when using this approach the displacements being solved
for, 𝒖(t), are relative displacements and not the total displacements.

For a more comprehensive review of the material presented in this theory section
see the book “Dynamics of Structures”, by Anil K. Chopra, specifically sections 1.7,
5.4, 5.7, 9.2 and 11.4.

12.2 Verification Examples:
A number of verification examples are provided to demonstrate the functionality
and that the mathematics of the implementation match the theory. A test protocol
also exists to test the functionality.

Example 1: An example of
a single story elastic
building subject to ElCentro
ground motion. Its purpose
is to study effects of
changing building
properties and PDelta
effects on the response for a
single degree-of-freedom
structure.

Purpose: A test of user requirements 1 and 2 for “elastic system”

Testing Procedure:
1) PDelta Not Included:
• User starts tool and enters the following:
o 1 for Number Floors,
o 386.4 for Building Weight,
o 100.0 for Building Height,
o Disable PDelta effects, i.e. uncheck the Include PDelta box.
o Entering Different Story Stiffness or K Values and Damping Ratio, the
user will see different values for Fundamental Period and Max
Displacement. For damping values of (0.00 and 0.05) and stiffness
values (157.9134, 39.4784, and 9.8696) these periods and
displacements should be as shown in the table. The numbers in the
brackets are those computed by Matlab generated by the script
MDOF1a.m (found in verification directory of tool source code)


Story Stiffness (K) Fundamental Damping Ratio Damping Ratio
Period 0.00 (0%) 0.05 (5%)
157.9134 0.50 (0.5000) 4.45 (4.4464) 2.24 (2.2420)
39.4784 1.00 (1.0000) 7.37 (7.3700) 4.42 (4.2229)
9.8696 2.00 (2.0000) 9.91 (9.9131) 5.38 (5.3771)

PDelta Included:

User repeats the process but with PDelta effects included. To do this the user
enters:

o 1 for Number Floors,
o 386.4 for Building Weight,
 o 100.0 for Building Height,
o Include PDelta Effects enabled, i.e. box checked.
o Entering Different Story Stiffness or K Values and Damping Ratio,
Zeta, the user will see different values for Fundamental Period and
Max Displacement. For damping values of (0.00 and 0.05) and
stiffness values (157.9134, 39.4784, and 9.8696) these periods and
displacements should be as shown in the table. The numbers in the
brackets are those computed by Matlab generated by the script
MDOF1b.m (found in verification directory of tool source code)

K Tn Damping Ratio Damping Ratio
0.00 (0%) 0.05 (5%)
157.9134 0.51 (0.5062) 3.19 (3.1898) 2.30 (2.3045)
39.4784 1.05 (1.0529) 6.58 (6.5804) 4.28 (4.2834)
9.8696 2.56 (2.5639) 15.40 (15.3972) 11.34 (11.3381)

Example 2: An example of a single story building subject to ElCentro ground
motion to study effects of nonlinearity on the response for a single degree-of-
freedom structure. The structure is as shown. In this test the user is modifying
the yield strength of the system.

Purpose: A test of user requirements 1.c for elastic and non-linear system and
requirement 4.a

Testing Procedure:
o User starts tool
o 1 for Number Floors,
o 386.4 for Building Weight,
o 100.0 for Building Height,
o 39.4784 for Story Stiffness
o 0.02 for Damping Ratio
o Include PDelta disabled, i.e. box unchecked
o Entering Different Story Fy values (250, 125, 60, 30) in spreadsheet,
the user will see different values for Max Displacement. The
fundamental period will be as in previous example. The numbers in
the brackets are those computed by Matlab generated by the script
MDOF2.m (found in verification directory of tool source code)

 Fy Max Displacement
250 5.93(5.933)
125 5.06(5.0611)
60 4.12(4.1190)
30 4.39(4.3863)

If user selects the view option, and selects Floor Displacement History, Story
Force History time Histories and Force Displacement Response they should see
the following windows:

The MDOF2.m script also produces output figures for same responses. The
output for Fy=30 is as shown below:


Example 3: To study the effects of changing building properties for a 5 story
building as shown. In this example we verify that the user can change properties
for individual floor and story components.

NOTE: many of the properties entered are similar to those on tool startup to
limit amount of user input required.

Testing Procedure:
o User starts tool
o User verifies number floors = 5, building weight = 500, building height
= 720, and damping = 0.05
o User Turns Off PDelta, i.e. PDelta Included unchecked
o The observed response quantities Tn and Max response for alpha=1.0
and beta = 1.0 are as displayed.
o User modifies properties of Floor Weight for floor 5 from 100.0 to 1.0
in spreadsheet portion and observes response quantities.
o Keeping Floor 5 weight at 1.0, user modifies floor 5 stiffness to .03154
and again observes quantities. Results are as shown in table versus
Matlab (MDOF3.m)

Alpha Beta M5 K5 Fundamental Max Disp
Period
1.0 1.0 100.0 31.54 2.00(1.9996) 6.83(6.8320)
0.01 1.0 1.0 31.54 1.64(1.6424) 5.72(5.7179)
0.01 0.001 1.0 0.03154 1.82(1.8174) 29.62(29.6194)

Example 4: User able to add their own ground motion to the tool. The input format
for a new motion is a JSON file containing an object with the records name, delta t,
and the recorded points in an array “data”. The units for the data points are g.
A test of user requirement 5.a.

{
"numPoints": 1560,
"name": "elC",
"dT": 0.02000,
"accel_data": [
0.00000,
0.00630,
..
..
]
}

An example file, elC.json, is provided in the tool example directory on github. This
motion is the same as the ELCentro motion, so results can be verified by using any of
the above examples; it is the ability of user to add a motion that is being tested.

Testing Procedure:
o User downloads example JSON file containing record.
o User starts tool
o User selects add button in Input Motion frame and loads the file.
o User should be presented with results for new motion.
o User can compare with other motions, by clicking on Input motion
pull down and selecting a different motion.

Example 5: User able to save and load any saved set of options. Test of user
requirement 3.

Testing Procedure:

o User starts tool
o User makes any number of changes.
o User selects save from file menu and provides name.
o User exits tool and starts again.
o User selected open from file menu, navigates and selects the file they
just saved. Properties and results should be as last saved.


13. Implementation on DesignSafe-ci.

The tool is built as a stand-alone desktop application for use on machines running
the Windows and macOS operating systems. It currently does not utilize
DesignSafe-ci resources. It is made for download through a webpage devoted to the
tool on a page hosted by DesignSafe-ci:

https://simcenter.designsafe-ci.org/learning-tools/multiple-degrees-freedom-
application/

14. User Training/ Support:

User Training consists of an online video available from the tool webpage that
demonstrates tool use. The tool will be presented in user workshops scheduled to
start in year 3 and at NHERI Summer Institute. (The alpha version of tool was
presented and distributed to select attendees at this year’s event, July 2017)

User support at present is a slack channel dedicated to the tool. SimCenter member
McKenna will monitor this channel.

15. Tool Iterations:

The following shows some of the design iterations that the tool has undergone from
initial sketchup through the different releases.

Original sketch up of tool developed by McKenna and Schellenberg.

Iteration 1 - Producing V0.1

A User workflow, a Wireframe with functional requirements was developed by
Rutman in consultation with Schellenberg and McKenna based on initial sketch. A
V0.1 prototype implementation was developed for the user group to evaluate. The
following shows the workflow.


The figure below shows screenshot from a working prototype and the original
wireframe developed for the tool. The wireframe shows the layout of the UI
elements. The second image shows the functional specification, basically the actions
and events that occur when the user interacts with UI elements:

Iteration 2 Producucing Version 0.2:

After feedback from Version 0.1, a second Wireframe and Prototype were
developed. Figure below shows a side by side comparison:

Iteration 3 - Producucing Version 1.0:

After user feedback from our expanded user group, a final Wireframe and
Prototype were developed for version 1.0. These are as shown in section 5.