Civil Engineering

Induction Book

Ruaumoko Manual

Volume 1:
Theory

Author:
Athol J. Carr
Department of Civil Engineering COMPUTER PROGRAM LIBRARY

Program nam e: Program type: Program code:

RUAUM OKO Inelastic Dynamic Analysis ANSI Fortran77

Author: Date:
Athol J Carr 29 April 2007

RUAUMOKO
The Maori God of Volcanoes and Earthquakes

Volume 1: Theory.

Copyright \ Athol J. Carr, University of Canterbury, 1981-2007. All Rights reserved.

Program Language.
The program s RUAUM OKO-2D, RUAUM O KO-3D, DYNAPLOT, COM BPLOT, SPECTRA, HYSTERES,
SIM QKE, PQUAKE, INSPECT, SURFACE and FPRINT are all written to the standard ANSI Fortran77 with a
few features from ANSI Fortran90 and Fortran95.

For further details or for help on problem s in running the programs contact,

Prof. Athol J. Carr,

Departm ent of Civil Engineering,
University of Canterbury,
Private Bag 4800,
Christchurch 1,
NEW ZEALAND..

Telephone +64 3 366-7001 Ext 6246 (University Exchange)

or +64 3 364-2246 (Direct)
or +64 3 358-4390 (Hom e Residence)

FAX +64 3 364-2758 (Departm ent of Civil Engineering)

(Note: +64 = New Zealand., 3 = South Island Area Code)

Electronic m ail; a.carr@ civil.canterbury.ac.nz

or athol.carr@ canterbury.ac.nz
 Table of Contents

1 INTRODUCTION .................................................................................................................................. 1

2 MODELLING ........................................................................................................................................ 1

3 MASS MATRIX ..................................................................................................................................... 2

4 DAMPING MATRIX .............................................................................................................................. 3

4.1 Rayleigh or Proportional Dam ping Models .............................................................................. 4
4.2 Caughey Dam ping ................................................................................................................... 6
4.3 Effects of Different Dam ping Models .................................................................................... 10
4.4 Recom m endation.....................................................................................................................14

5 STRUCTURAL MEMBERS ................................................................................................................ 18

5.1 Fram e Mem bers .................................................................................................................... 18
5.2 Spring Mem bers .................................................................................................................... 21
5.3 Dam ping or Dash-pot Mem bers ............................................................................................ 22
5.4 Constant-Force and Active-Tendon Mem bers ...................................................................... 22
5.5 Contact Mem bers .................................................................................................................. 23
5.6 Quadrilateral Finite Elem ents ................................................................................................ 24
5.7 Masonry Panel Elem ents ...................................................................................................... 25
5.8 Foundation or Ground Elem ents ........................................................................................... 26
5.9 Structural W all Mem bers........................................................................................................ 27

5.10 Five Node Definition of One Dim ensional and Two Dim ensional Mem bers ......................... 28
5.11 Stiffness Matrix ...................................................................................................................... 29

6 STIFFNESS AND STRENGTH DEGRADATION ............................................................................... 30

6.1 Hysteresis Rules for Stiffness Degradation ........................................................................... 30
6.2 Strength Degradation ............................................................................................................ 37

7 APPLIED LOADS ............................................................................................................................... 38

7.1 Static Loads ........................................................................................................................... 38
7.2 Earthquake Ground Acceleration Excitation ......................................................................... 38
7.3 Earthquake Ground Displacem ent Excitation ....................................................................... 38
7.4 Dynam ic Force Excitation ...................................................................................................... 38
7.5 Active-Tendon Loading ......................................................................................................... 38
7.6 Pushover Analysis ................................................................................................................. 39
7.7 Adaptive Pushover ................................................................................................................ 39
7.8 Cyclic Adaptive Pushover ...................................................................................................... 42

8 MODAL ANALYSIS ............................................................................................................................ 43

8.1 Reduction of Eigenvalue Problem for Degrees of Freedom W ithout Mass .......................... 44

9 TIME-HISTORY INTEGRATION ........................................................................................................ 46

9.1 Newm ark Constant Average Acceleration Method ............................................................... 46
9.2 Explicit Central Difference Method ........................................................................................ 48

10 SMALL and LARGE DISPLACEMENTS ............................................................................................ 49

11 RELATIVE or TOTAL DISPLACEMENTS .......................................................................................... 50

12 GENERAL PROCEDURES ................................................................................................................ 53

12.1 Free-Form at Input ................................................................................................................. 53
12.2 Units ...................................................................................................................................... 53
12.3 Num bering ............................................................................................................................. 53

i
13 RESULTS ........................................................................................................................................... 54
13.1 Initial Input Echo .................................................................................................................... 54
13.2 Static Analysis ....................................................................................................................... 54
13.3 Modal Analysis ...................................................................................................................... 54
13.4 Dynam ic Tim e-History ........................................................................................................... 54

14 SIGN CONVENTIONS ....................................................................................................................... 55

14.1 Nodes - Displacem ents and Forces ...................................................................................... 55
14.2 Fram e and Foundation Mem bers Displacem ents and Forces ........................................... 55
14.3 Spring, Dam per, Tendon and Contact Mem bers .................................................................. 56
14.4 Quadrilateral Finite Elem ent .................................................................................................. 57
14.5 Masonry Panel Elem ents ...................................................................................................... 57

15 GRAPHICS ......................................................................................................................................... 58
15.1 On-Screen Graphics ............................................................................................................. 58

16 DUCTILITIES ..................................................................................................................................... 59
16.1 Giberson Beam s and Mem ber Ductility ................................................................................. 59
16.2 Beam Colum n Mem bers ....................................................................................................... 64

17 DAMAGE INDICES ............................................................................................................................ 65

18 ENERGY ............................................................................................................................................ 66

19 REFERENCES ................................................................................................................................... 67

The following sections are num bered separately:

Exam ples for the use of the program Ruaumoko-2D

Inform ation on the structure of the ASCII form at post-processor files.

Inform ation on the com m and processor TINYCLIP used by all the program s in the Ruaum oko suite of
program m es.

ii
 RUAUMOKO
The Maori God of Volcanoes and Earthquakes

Athol J Carr.

Maori m ythology records that Ruaum oko was the last of a fam ily of seventy, the son of Rangi, the Sky-father, and
Papa, the Earth-m other. He was still at the breast when the Earth-m other was turned over on her face by her
other sons to im prove the weather conditions, and was thus carried under. He is stated to be inim ical to m an and
now and then he sends an earthquake or a volcanic disturbance to destroy him .

1 INTRODUCTION
The program RUAUMOKO is designed to produce a piece-wise tim e-history response of non-linear general
two-dim ensional and three-dim ensional structures to ground accelerations, ground displacem ents or tim e
varying force excitations. The program m ay also be used for static or pushover analyses of structures.

2 MODELLING
Several different options are available for the m odelling of the Mass, Dam ping and Stiffness m atrices for the
structure. The user is expected to use those m ost appropriate to the form of structural fram e that is being
analysed. The technical literature has very scant reference to the m odelling of non-linear structures and som e
of the references quoted in this m anual m ay help the new or inexperienced user of the program .

The program has a wide variety of m odelling options available to represent the structure and its supports and
interactions with adjoining structures. The m ass representation is via lum ped or kinem atically consistent m ass
m atrices.

The dam ping exhibited by the structure can be m odelled by the com m only assum ed Rayleigh dam ping m odels
or by a range of m odels aim ed to give a better representation of the variation of fractions of critical dam ping with
frequency as well as options for different levels of dam ping in different parts of the structural system .

There are a wide variety of m em bers available to represent the structural system such as fram e type m em bers,
quadrilateral finite elem ent m em bers and special m em bers to represent special effects such as spring and
contact or im pact m em bers to represent contact between adjoining structures. There are also foundation
m em bers to represent soil-structure interaction effects and to represent through-soil coupling between adjoining
structures. There is a large num ber of different hysteresis rules available that m ay be used to represent the force-
displacem ent relationships in the different fram e, spring, contact and foundation m em bers m entioned above.

There are a wide range of tim e-history excitations that m ay be applied to the structure. The excitation m ay be
in the form of ground accelerations and these m ay be applied as a rigid-body ground m otion or as a travelling
wave acceleration history. The input m ay be in the form of tim e-varying dynam ic loading histories or in the form
of ground displacem ent histories. There are also provision for conventional push-over analysis or with an
adaptive push-over analysis for both m onotonic loading or as a form of cyclic excitation.

1
3 MASS MATRIX
The m ass of the structure is input in the form of weights and internally converted by the program to m ass units
by dividing the weights by the acceleration of gravity. The m ass m ay be provided by both specified nodal weights
or by m em ber weight/unit length or elem ent m aterial density. Nodal weights will contribute to only the diagonal
term s of the m ass m atrix where the term s associated with the rotational degrees of freedom are usually taken
as zero. However, the user has the option of providing a rotational inertia if this is felt to be appropriate. The x,
y and z inertia quantities may be different in a structure particularly in a two-dim ensional analysis where the fram e
being analysed is flanked by adjoining fram es which carry vertical loads but have relatively insignificant lateral
stiffness. In this case the vertical inertia is associated only with that of the fram e being analysed while the
horizontal inertia has to represent the sum of the inertia contributions of all fram es being supported, in the lateral
direction, by the fram e being analysed.

The m em ber contributions to the m ass m atrix m ay take one of three form s, governed by the variable IPCONM
in the first param eter line of the input data.

There is a Lum ped m ass representation where contributions are m ade to the diagonal term s associated with the
three translational degrees of freedom at each end of the m em ber or to all four nodes for quadrilateral or panel
elem ents with no contribution to the rotational degrees of freedom .

The Diagonal m ass representation is the sam e as the Lum ped m odel above except that the contribution to the
rotational degrees of freedom is equal to the diagonal term of the appropriate consistent m ass m atrix of the
m em ber concerned for beam , beam -colum n and wall elem ents. [see Cook, 1981]

The third option is the Consistent m ass representation using the kinem atically equivalent m ass m atrix [Clough
1993] where inertia forces are associated with all degrees of freedom . This will result in a m ass m atrix with the
sam e banded skyline form as that of the stiffness m atrix.

The Consistent m ass m odel requires a greater computational effort in the m ultiplication by the nodal
accelerations to get the inertia forces at each tim e-step in the analysis. It also bounds all natural frequencies and
consequently gives a slight bias to the frequency content of the structure.

If the only m asses are those from the input nodal m asses there is no difference in the actual m ass m atrices for
the structure though the consistent m ass option would involve the extra cost of m ultiplying all the zero term s
within the m atrix skyline of the associated stiffness m atrix when com puting the inertia forces.

The m ass m atrix used for the m ode shape and frequency analysis is a diagonal m ass m atrix. As the com puted
free-vibration frequencies are only used for checking purposes and for com puting the dam ping m atrix this is of
little consequence. To use the consistent m atrix would require a double eigenvalue solution or the Cholesky
decom position of the m ass m atrix. The first approach is com putationally expensive and the second is not possible
if there are any degrees of freedom without m ass as the m atrix would then be singular. If a Rayleigh dam ping
m atrix is being specified then the frequencies are used to com pute the contributions of both the m ass and
stiffness m atrices to the dam ping m atrix. If the dam ping m atrix is form ulated using the approach of Penzien and
W ilson then all m ode shapes and frequencies of free-vibration m ust be com puted. Once the step-by-step tim e
integration is started, then the specified form of the m ass m atrix, Lum ped, Diagonal or Consistent, is used for
all subsequent com putational steps.

If rigid floor diaphragm s are being used in the m odelling of three dim ensional structures then the m aster node
of the floor should be located at the centre of m ass of the floor as during the m odal analysis the m ass m atrix is
diagonalized. The m aster node should also be at the centre of m ass if a lum ped or diagonal m ass m atrix is being
used as there is then no way of expressing the m ass coupling between the rotational and translational degrees
of freedom .

2
4 DAMPING MATRIX
There are several dam ping m odel options available within the program . The traditional approach has been to use
a Rayleigh or Proportional dam ping m odel where the structures dam ping matrix C is given by

where M and K are the m ass and stiffness m atrices for the structure. The coefficients " and $ are com puted to
give the required levels of viscous dam ping at two different frequencies, m ost com m only those of the first and
second m odes of free vibration.

Figure 1 Rayleigh or Proportional Damping M odel

Rayleigh dam ping m ay be m odelled proportional to the tangent stiffness m atrix or the initial stiffness m atrix.
Variable ICTYPE in the first line of the input data controls the selection of the dam ping m odel. As a general guide
the user should endeavour to ensure that the fraction of critical dam ping in the highest m odes is less that 100
percent. RUAUMOKO com putes the fractions of critical dam ping at all frequencies for the selected dam ping
m odel. The coefficients " and $ m ay also be specified directly by the user.

W ork by Crisp [Crisp 1980] showed that high levels of viscous dam ping in the high m odes of free vibration of a
structure has a m arked effect on the response of an inelastic structure. The use of the tangent stiffness was
criticized from the philosophical point of view in that when the structure goes inelastic one did not expect the
dam ping to reduce. However, it appears that this reduction of the dam ping partially com pensates for the
excessive higher m ode dam ping associated with the Rayleigh dam ping m odel. W ith tangent stiffness dam ping
the fractions of critical dam ping in the structure tend to rem ain m ore constant as the stiffness of the structure
reduces whereas the constant m ass and initial stiffness dam ping contributions im ply increasing fractions of critical
dam ping as the stiffness of the structure reduces with inelastic response.

In the response of inelastic structures to earthquake excitation a step-by-step integration of the equation of
dynam ic equilibrium is required as the non-linearity of the structure precludes the use of super-position and hence
any m odal m ethods such as the use of response spectra techniques. This m akes it difficult for the engineer in
that the structure m ust be analysed for all the load cases sim ultaneously as the separate gravity and seism ic

3
excitation responses cannot be obtained and com bined for alternate excitation directions as is traditionally used
in seism ic design.

In inelastic structures various hysteresis rules are used to represent the inelastic behaviour of the m em ber
actions, such as the m om ent-curvature relationships in beam m em bers. These non-linear rules allow for the
energy dissipation due to the non-linearity of the m em bers and although these m em bers do not go through very
m any com plete hysteresis loops within a single earthquake excitation the large forces associated with these
m em ber hysteresis loops m eans that a considerable amount of energy is rem oved from the structural response.
However, these hysteresis m odels do not, in general, account properly for the energy rem oved from the system
by sm all cycle oscillations within the structure. Even structures that rem ain elastic show a dam ped response and
the effect of this low level dam ping in the structure has a m arked effect of the response of the structure. An
exam ination of any earthquake response spectrum will show that even sm all am ounts, i.e., 2 to 5%, of critical
dam ping will significantly reduce the response of the structure. Som e suitable dam ping m odel is required in the
analysis to represent this decay. W hether the dam ping in the structure is actually viscousor hysteretic is
som ething that has yet to be determ ined, but in the m eantim e it is generally assum ed to be a viscous dam ping
m echanism . This is usually justified in that as the dam ping forces are assum ed to be sm all any error due to this
m athem atically convenient assum ption is not very significant in the response. This appears to be reasonably well
justified in term s of an elastic response.

However, during the past two decades the author and his research colleagues have been increasingly concerned
at the effects that poor choices of dam ping m odel have had on the inelastic responses of fram ed structures. Most
analysts assum ed that if they specified say 5% of critical dam ping at two m odes then their structure had
effectively 5% of critical dam ping. It was found in 1979 on exam ining the response of som e fram ed structures
that som ething appeared to be seriously wrong with joint equilibrium . At an interior joint in the fram e, the two
girders fram ing into the joint had yielded with elasto-plastic yield m om ents of approxim ately 1000 kNm each and
yet the sum of the colum n m om ents at the joint was of the order of 3000 kNm . The joint appeared to have an out-
of-balance m om ent of approxim ately 1000 kNm . On m odification of the program to com pute and output the joint
forces and m om ents associated with the dam ping m atrix, the 1000 kNm was found to be a dam ping m om ent at
the joint.

Crisp [Crisp, 1980] showed that this fram e had approxim ately 300% of critical dam ping in its highest m odes and
that the large dam ping m om ents were associated with large local rotations relative to the lateral displacem ents
as a consequence of the local yielding of the m em bers connected to the joint in question. Since that research
work we have strongly recom m ended that when a Rayleigh dam ping m odel is being used the frequencies at
which dam ping is specified m ust be chosen to ensure that the highest m odes of free-vibration in the structure
are sub-critically dam ped.

In m ore recent tim es users of inelastic analyses have reported large apparent losses of equilibrium even in push-
over analyses of sim ple two m em ber structures by step-by-step dynam ic analysis where the dam ping m om ents
and forces have been found to reach about 50% of the mom ent and shear force acting at the base of the
structure. In hindsight the users recognised that they should have been aware of the problem but thought that
as the loads were increased slowly in the pushover analyses that the velocity term s would not be a problem . Once
yielding occurs the deform ations are often very localized resulting in relatively high local deform ation velocities.

4.1 Rayleigh or Proportional Damping M odels

The traditional dam ping m odel available in m ost step-by-step or tim e-history program s is the Rayleigh or
Proportional dam ping m odel.

The reason for its popularity is that it uses m atrices that the analysis already has com puted and requires only the
com putation of the two coefficients " and $ in order to form a dam ping m atrix so that the analysis m ay be carried
out. In m any of the program s it is left to the user to estim ate the two frequencies at which the required am ount
of dam ping is specified in order to evaluate the two coefficients. Assum ing that the properties of orthogonality
of the m ode shapes of free-vibration with respect to the m ass and stiffness m atrices also applies to the dam ping
m atrix it is possible to specify the desired dam ping levels at two frequencies. If the required fractional of critical

4
dam ping is 8 i and 8 j at m odes i and j with natural circular frequencies T i and T j respectively then

and

The result of this assum ption is that at any other m ode with natural circular frequency T n the fraction of critical
dam ping is given by

This relationship between dam ping and natural frequency of free vibration is shown in Figure 1 where it is seen
that as the natural frequency increases the am ount of dam ping increases alm ost linearly with frequency. The
m ajor popularity of the Proportional dam ping m odel is that it uses the m ass and stiffness m atrices of the structure
and which are already com puted within the analysis. Furtherm ore, the skyline or shape of the dam ping m atrix
is identical with that of the stiffness m atrix, and with that of a consistent m ass m atrix, and therefore does not
increase the size of m atrices used in the dynam ic analysis and does not affect the com putational effort at each
tim e-step.

Another consideration required in setting up the analysis is whether to use the initial elastic stiffness m atrix, the
current tangent stiffness m atrix or a com bination of both of them .

In the early analyses by Sharpe [Sharpe, 1974] a tangent stiffness m atrix was used as this is the current stiffness
m atrix at any tim e step and is available whereas the initial stiffness m atrix would have had to retained as an extra
m atrix carried right through the analysis. There were objections to the use of the tangent stiffness by the thesis
exam iners on the grounds that as the structure becam e inelastic and the stiffness reduced so did the dam ping
m atrix which did not seem reasonable. The program was then m odified to use either the initial elastic stiffness
or the current tangent stiffness with the form er becom ing the norm for our analyses in the following years.

If the dam ping rem ains constant as the structure yields resulting in a decrease in the stiffness, and the natural
frequencies, then the fractions of critical dam ping in the structure increase. Although extra dam ping is expected
this is m odelled by the m em ber hysteresis and should not be effected twice by an increase in the viscous
dam ping as well. The effect of increasing the fractions of critical dam ping as the stiffness reduces m ay be partially
offset by using the tangent stiffness m atrix instead of the initial stiffness dam ping. In this case the dam ping m atrix
reduces at the sam e tim e as the stiffness reduces.

A variant of the Rayleigh dam ping m odel is the m ass proportional dam ping m odel where $ is set to zero. If the
m ass m atrix is diagonal, which is a very com m on assum ption, then the dam ping m atrix is also diagonal
sim plifying the analysis. The consequence is that the fraction of critical dam ping is inversely proportional to the
frequency which im plies very sm all am ounts of dam ping in the higher m odes of free-vibration and which does
not appear to be very realistic.

5
4.2 Caughey Damping

A m eans of m atching the required am ount of dam ping at a greater num ber of m odes is provided by a dam ping
m odel proposed by Caughey [Caughey 1960] where the dam ping m atrix m ay be expressed as

where q = any integer

N = num ber of nodes at which dam ping is specified.

This equation enables the fraction of critical dam ping to be expressed at all, or any, of the natural frequencies
of free vibration. The difficulty is the large powers of T required in the expressions to evaluate the coefficients
a b and the com putationally awkward m atrix products involved. W ilson and Penzien [W ilson and Penzien 1972]
proposed a m uch sim pler way of obtaining the sam e dam ping m odel using the N m ode shapes of free-vibration.
The disadvantage of this approach is the large eigenvalue problem to be solved for all N natural frequencies and
m ode shapes of free vibration before com m encing the tim e-history analysis as well as the other disadvantage
of the Caughey dam ping m odel in that the dam ping m atrix C is fully populated, i.e. it is no longer a banded m atrix.
This latter effect increases greatly the m em ory requirem ents of the analysis as well as the com putational effort
at each tim e-step.

The m ethod suggested by W ilson and Penzien m akes use of the properties of orthogonality of the m ode shapes
with respect to the m ass, dam ping and stiffness m atrices. Given the ith m ode shape of free-vibration N i such that

where m i is the generalised m ass for the ith m ode. In a sim ilar m anner the generalised dam ping can be
com puted from

If the fraction of critical dam ping 8 is specified for each m ode then the dam ping m atrix C can be obtained using
the inverse of the m odal m atrix to transform back from the generalised dam ping m atrix. The actual operation m ay
be sim plified and the reader is referred to the original paper of W ilson and Penzien for further details.

Figure 2 Linear or Tri-linear Damping M odel

In RUAUMOKO there are incorporated three different versions of this dam ping m odel. The first assum es a linear
variation of the fraction of critical dam ping with frequency where the user specifies the dam ping required at any
two m odes. If the sam e fraction of critical dam ping is specified at both m odes then constant dam ping is provided
at all frequencies. The second version assum es that the dam ping is constant at frequencies below the first

6
nom inated m ode with a linear variation of the fraction of critical dam ping to the fraction of critical dam ping
specified at the second specified m ode and then rem ains constant to the highest frequency m ode in the structure.
A third m odel, sim ilar to the second, but having linear interpolations used between up to 9 interm ediate m odes
nom inated in between the first and last specified m odes.

Figure 3 User Specified Modal Damping

The second tri-linear m odel was used by Crisp [Crisp, 1980] who analysed a 6 storey fram e where the dam ping
was specified at m ode 1 and the highest m ode in the structure to show that the problem of joint equilibrium was
in high dam ping associated with the high m odes. Initially dam ping in the highest m ode was set to that of the Initial
stiffness Rayleigh dam ping m odel with 5% of critical damping in m odes 1 and 2 to give sim ilar results. Then the
dam ping in this highest m ode was progressively reduced over a series of analyses to a uniform dam ping across
all m odes. The displacem ents of the structure increased progressively to the case where they virtually m atched
those of the tangent stiffness Rayleigh dam ping m odel with 5% dam ping at m odes 1 and 5. Since that tim e we
have generally recom m ended that Rayleigh dam ping be specified at m ode 1 and at a m ode num ber equal to,
or a little less than, the num ber of storeys in the fram e.

These latter three dam ping m odels result in a fully populated dam ping m atrix with a large increase in m em ory
requirem ents and com putational effort. In the first stage all natural frequencies and their associated m ode shapes
of free vibration have to be com puted to generate the dam ping m atrix. If, with structures that have a very large
frequency spectrum , som e of the highest frequencies are com plex because of num erical difficulties in separating
the high m ode frequencies, these m odes are assum ed undam ped. In the tim e-history analysis, the coefficients
of the dam ping m atrix within the skyline of the stiffness m atrix are kept on the left hand side of the equations of
dynam ic equilibrium while the rem aining coefficients operate in a predictor-corrector iteration process within each
tim e step. This iteration is controlled by the param eters M AXCIT and FTEST, which should be set to 1 or 2 and
0.010 or 0.001 respectively. Further details m ay be found in [Crisp 1980]. In all the analyses carried out to date
only one iteration was required at each tim e-step to achieve the desired accuracy.

The program besides having the above dam ping m odels and the Rayleigh dam ping m odels using either the initial
or tangent stiffness m atrix has a further option where different " and $ m ay be specified for each m em ber in the
structure. This not m eant to im ply great generality but to enable different structures, say, in carrying out a
pounding study between a steel fram e and a reinforced concrete fram e to have different levels of dam ping in
each fram e. It m ay also be used in foundation-structure interaction studies where different levels of dam ping m ay
be expected in the structure and in the foundation m odel. The appropriate " and $ values would be com puted
by analysing the individual structures, specifying the dam ping required at the two m odes specified using the
Rayleigh dam ping m odel and then using the com puted " and $ as part of the section properties for the m em bers
in the different structures etc. (See figures 4 and 5.)

7
RUAUMOKO also has specific translational and rotational DAMPING m em bers or dashpots which m ay have
linear or non-linear force-velocity relationships. The properties m ay also differ in the positive and negative
directions. The dashpots m ay have a displacem ent gap where the dam ping coefficient is zero. These m em bers
are designed to represent special dam ping devices inserted in the structure and where the properties have been
evaluated from laboratory experim ents.

Dam ping is also associated with CONTACT m em bers but only acts whilst the contact m em bers are actually in
contact. Dam ping can also associated with the GROUND or foundation m em bers. The Elastom eric Dam per
hysteresis rule also has velocity dependant dam ping forces associated with the elastic forces and stiffness of the
m em ber.

Note that the dam ping only affects the structure during the tim e-history analysis and has no effect on the static
analysis or on the frequency and m ode shape analysis..

8
Figure 4 Different Damping in Different Parts of M odel

Figure 5 Different Damping in Different Structures

9
4.3 Effects of Different Damping M odels

The m ajority of non-linear dynam ic engineering software allows only the use of the Rayleigh or Proportional
dam ping m atrices and in a large num ber of the cases this is specified in term s of the coefficients " and $ and
the choice of the use of the initial and tangential stiffness m atrices. In som e cases separate values of $ m ay
be specified for a com bination of the initial and tangential stiffness m atrices. To get the coefficients so that a
required level or fraction of critical dam ping is attained the m odal properties i.e. the natural frequencies of free-
vibration will often have to be estim ated in som e external procedure. In m any cases the dam ping m odel is
given scant consideration as there is the belief that as the dam ping forces are sm all and that as a correct level
of dam ping has been specified then no further consideration is required.

In an elastic analysis of a N storey fram ed structure subjected to a lateral earthquake excitation only the first
N sway m odes have any significant contribution to the response and the higher m odes associated with local
joint rotations etc. will have a negligible contribution to the response.

As a result of nearly three decades of dynam ic analyses of fram ed structures we have found that the m ass
representation of the fram e has a considerable effect on the response of the m em bers when inelastic
behaviour takes place and the usual m odels include associating m ass with all joints in the fram e including
som e m ass associated with the rotational degrees of freedom . This latter feature is m ost im portant if the fram e
m em bers are m odelled with elasto-plastic mom ent-curvature relationships. The horizontal degrees of freedom
in a floor m ay be slaved together, except in pounding studies where it has been found that the axial
deform ation of the floor girders is im portant when estim ating the m agnitude of the contact or im pact forces.
The problem with such m ass m odels of the structure is that the num ber of independent dynam ic degrees of
freedom increases considerably. W ith the increase in the fractions of critical dam ping with increasing
frequency associated with the Rayleigh dam ping m odel this m eans that although the lower m odes of free-
vibration m ay have of the order of say 5% of critical damping it is very easy to get very large levels of dam ping
in the higher m odes where the natural circular frequencies m ay be of the order of several thousand radians
per second.

W hen elastic structures are subjected to earthquake excitation only the lateral sway m odes of the structure
are excited by the ground m otion. As these m odes have low natural frequencies, in an N storey fram e the Nth
sway m ode frequency is approxim ately (2N-1) tim es the fundam ental m ode frequency, the highest m ode
contributing significantly to the response is still lowly dam ped. Even when relatively low levels of inelastic
behaviour are observed in the fram e and the higher m odes are being excited their contributions are still sm all
and the sm all m odal velocities only result in sm all dam ping forces and m om ents. However, when the fram e
is subjected to strong ground m otions, large m em ber in-elastic rotations occur at the m em ber ends. These
rotations are now relatively large joint rotations with respect to the lateral joint displacem ents (see Figure 7).
If the equal displacem ent principles are correct then such displacem ents would norm ally be associated with
the m uch sm aller rotations that are observed in the longer period sway m odes of the fram e. The extra
rotations can be considered as being supplied by the higher frequency joint rotation m odes. Unfortunately ,
as a result of the Rayleigh dam ping m odel, these higher frequency m odes have relatively high dam ping ratios
associated with them . The large higher m ode velocities which are only observed as inelastic behaviour occurs
result in large dam ping forces and m om ents at the joints of the fram e. These dam ping forces affect the
equations of dynam ic equilibrium thereby affecting the displacem ents of the structure as well as the in-elastic
displacem ents of the m em bers in the fram e.

To illustrate these effects [Carr, 1997] a 12 storey, 2 bay fram e (see Figure 6) is subjected to the Pacoim a
Dam excitation recorded during the San Fernando earthquake in California in 1971. This earthquake provides
m uch greater accelerations than are expected for a design earthquake im plied in the New Zealand Loadings
Code [NZ4203,1992] but this record has been used as an exam ple of a m axim um credible event in order to
evaluate the ultim ate response of structures designed to the norm al code design provisions. The building has
an inter-storey height of 3.650 m and the span of each bay is 9.200 m . The structure is designed to the 1984
version of the code and has a natural period of free vibration of 1.88 seconds. As all degrees of freedom in
the fram e have m ass associated with them and as all the horizontal degrees of freedom at a level are coupled
the fram e has a total of 84 degrees of freedom . An elasto-plastic hysteresis rule is used for all beam m em bers
and the ground floor colum ns. Following capacity design principles, the upper colum ns are designed to rem ain
elastic.

10
 Figure 6 12 Storey Fram e

Figure 7 Typical Frame Deformations

11
This fram e has m ass at all nodes, including rotational inertias. The horizontal displacem ents at all nodes on a
floor are slaved so that there are seven degrees of freedom at each floor, one horizontal displacem ent, three
vertical displacem ents and three rotations. This m eans that there are 84 dynam ic degrees of freedom in the 12
storey fram e.

Seven different dam ping m odels were used

1 Rayleigh dam ping using the initial, or elastic stiffness m atrix and with 5% critical dam ping in m odes 1 and
2. As a result of the dam ping m odel m ode 84 has 161% of critical dam ping.
2 As above but 5% critical dam ping in m odes 1 and 10. Mode 84 now has 36% of critical dam ping.
3. As for m odel 1 above but using a tangent stiffness Rayleigh dam ping assum ing a tangent dam ping
m atrix is used.
4. As for m odel 2 above but using a tangent stiffness Rayleigh dam ping assum ing a tangent dam ping
m atrix is used..
5. As for m odel 1 above but using a tangent stiffness Rayleigh dam ping assum ing a secant dam ping m atrix
is used.
6. As for m odel 2 above but using a tangent stiffness Rayleigh dam ping assum ing a secant dam ping m atrix
is used.
7. Using the m ethod suggested by W ilson and Penzien with a constant level of 5% of critical dam ping in
all m odes of free-vibration

It m ust be stressed that in all of these analyses the only difference in the data is in the dam ping m odels. In all
cases 5% critical dam ping has been specified. It will be noted that in cases A and C above the dam ping in m odes
2 and 3 drops to the order of 2.5% of critical dam ping. For m odels 1, 2 and 7 above the dam ping m atrix is
constant i.e. the initial (elastic), tangent and secant m atrices are the sam e.

The earthquake chosen for the exam ple is the Pacoim a Dam recording taken during the 1971 San Fernando
earthquake. This accelerogram is shown in Figure 8 and the displacem ent response spectra for the excitation
is shown in Figure 9 where for the fundam ental natural period of free-vibration of 1.95 seconds, assum ing 5%
viscous dam ping, the roof displacem ent is expected to be of the order of 0.5m . This m ight be com pared to the
0.2m displacem ent expected for such a building in W ellington city, the capital of New Zealand. This m eans that
the Pacoim a Dam acceleration record is stronger than a design level earthquake for W ellington.

Figure 10 shows the differences in the roof displacem ent when the fram e is subjected to the Pacoim a Dam
excitation. The com m only used initial stiffness Rayleigh dam ping where the " and $ are com puted from dam ping
specified at the first and second m odes of free vibration, shows sm aller responses. W hich response do you
want?

It can be seen that the displacem ents are m arkedly affected by the choice of dam ping m odel. Sim ilar effects also
show in the displacem ents at the m id-height of the fram e. The base shears of the fram es are sim ilar in all of the
analyses but there are significant differences in the ductility requirem ents of the girders in the fram e.

Figure 11 shows the different dam ping m om ents generated at the central joint at the level above the ground floor.
The general assum ption that the dam ping forces are small is not obvious in all these analyses. In the case of
initial stiffness Rayleigh dam ping where the 5% of critical dam ping is specified in m odes 1 and 2 dam ping
m om ents of 500 kNm , alm ost half the yield m om ent in the adjoining girders, are shown. The tangent stiffness
Rayleigh dam ping m odels and the constant dam ping m odel show quite sm all dam ping m om ents. It will be seen
that the large dam ping m om ents are very transitory in nature and can be shown to occur when the adjacent
girders are yielding or just returning to an elastic state.

Figure 12 shows the dam ping forces acting at level 1 of the fram e for the three of the dam ping m odel. The usual
assum ption by engineers is that the dam ping forces are sm all in com parison with the other forces acting in the
structure. For a single degree of freedom structure with 5% of viscous dam ping the dam ping force is of the order
of 10% of the total inertia force or elastic force in the structure. If the structure is inelastic and the dam ping
coefficient is help constant then the dam ping force m ay reach near 20% of the other forces in the structure.
Figure 13 shows the relative inertia force at level 1 (the relative inertia force is the m ass tim es the relative
acceleration whereas the total inertia force is proportional to the total acceleration the relative acceleration plus
the ground acceleration). It can be seen that for the case of Rayleigh Dam ping using the initial stiffness m atrices
the dam ping forces are at tim es quite large com pared with what is expected. This is not so when constant, or
uniform , dam ping is applied to all m odes. It m ust be noted that is the am ount of inelastic behaviour is sm all then
the differences seen in the results for the different dam ping m odels are also sm all.

The different analyses also show significant differences in the total acceleration records produced at the roof level
and the roof acceleration spectra show alm ost a 50% variation in the short period responses.

12
In order to show that the results are not strongly dependant on the choice of hysteresis m odel the analyses were
repeated for the case where the Clough degrading m odel was used for all inelastic action in the beam s or girders.
Although the tim e-history plots show a different response, the peak displacem ents for all dam ping m odels are
alm ost identical to those with the elasto-plastic hysteresis. The dam ping m om ents show sim ilar m agnitudes to
those for the elasto-plastic m odels but there is a greater num ber of large dam ping m om ent spikes.

In the work done by Crisp [Crisp 1980] on a 42 degree of freedom 6 storey fram e the linear and tri-linear dam ping
m odels increased the com putational effort required for the analyses by approxim ately 50%. In these earlier
analyses the structure stiffness m atrix was in the form of a constant bandwidth m atrix and not the skyline
equation solver used in the current version of RUAUMOKO with its optim ised equation num bering. There is an
increase in com putational effort because of the necessity to carry out the eigenvalue analysis to get all the m ode
shapes and frequencies of free-vibration and because the resultant dam ping m atrix is fully populated. In
RUAUMOKO the com putational effects of this are reduced by leaving only those term s within the skyline of the
stiffness m atrix on the left-hand side of the equations of increm ental equilibrium and putting the off-band term s
on the right-hand side and solving by iteration. It has never required m ore than one iteration to get a satisfactory
solution. However as the num ber of degrees of freedom increase the num ber of coefficients in the off-band part
of the m atrix increases involving greater com putational effort. Using a m odern unix workstation with real-tim e
graphics, or current Microsoft W indows operating system s there is no appreciable difference in the tim es
required for the analysis cases 1 through 7. If the graphics is suppressed then the com putational tim es are
reduced by about 45% with case 7 taking about 12% m ore tim e than case 1. This m eans that there is now little
significant penalty in using the dam ping m atrices proposed by W ilson and Penzien. The only difficulty is that, at
the m om ent, these are based on the initial stiffness m atrix which m eans that the effective dam ping ratios will rise
above 5% when the structure yields.

It has been found that if one uses the dam ping m atrix proposed by W ilson and Penzien then degrees of freedom
without m ass are also undam ped. This follows from the equation of free-vibration.

where refer to the parts of the m ode shape associated to degrees of freedom with and without m ass
respectively.

It is obvious that the elastic forces associated with the mode shape m ust be self-equilibrating at the non-m assed
degrees of freedom as no external forces can be present. This effect results in the dam ping forces associated
with the m ode shape being zero at those degrees of freedom without m ass.

There is another consideration that m ust be considered when using a tangent stiffness dam ping m odel and that
is the way that the dam ping acts in the structure. W hen the Rayleigh tangent stiffness dam ping m odel is applied
to the increm ental equations of equilibrium as part of the Newm ark integration m ethod the dam ping m atrix using
the Rayleigh dam ping m atrix is the tangent dam ping m atrix.

In the equations of increm ental equilibrium as set out for the Newm ark integration schem es (see the text by
Clough and Penzien or that by Chopra) the m ass, dam ping and stiffness m atrices required are all tangent
m atrices. These give the increm ent of inertia, dam ping or elastic forces due to the increm ents of acceleration,
velocity and displacem ent. Most dynam ic analysis program s still use the increm ental equilibrium equations in
their im plem entation of Newm arks m ethods of tim e-step analysis. In nearly all cases the changes in the m ass
m atrix are assum ed to be insignificant or inconsequential and the m ass m atrix is help to be constant throughout
the analysis. All the dynam ic tim e-history program s use the tangent stiffness m atrix which will change every tim e
step where the properties of the m em bers change. In all the early dynam ic analyses the dam ping m atrix was
based on the elastic stiffness m atrix, was therefore a constant m atrix so that the elastic, tangent and secant
m atrices are the sam e. The problem of using the initial stiffness is that as the natural frequencies of the structure
reduce as cracking or yield takes place, the dam ping coefficient rem ain constant im plying that the fractions of
critical dam ping increase. The idea of using the tangent stiffness m atrix to form the dam ping m atrix partially
com pensates for this by reducing the dam ping coefficients partially in line with the reduction of the natural
frequencies of free-vibration

13
In the m id-1980s Ruaum oko was changed from using the equations of increm ental equilibrium to using, at each
tim e-step, the equations of equilibrium at the end of the tim e step. The forces art the end of the tim e-step are
those at the beginning of the tim e-step plus the tangent m ass, dam ping and stiffness m atrices m ultiplied by the
increm ent in acceleration, velocity and displacem ent respectively. This result is that the inertia forces, dam ping
forces and elastic forces are com puted at every tim e step to ensure dynam ic equilibrium is enforced. If the
dam ping m atrix is constant the dam ping forces m ay be obtained by the increm ental sum m ation described above
or by m ultiplying the current velocities by the dam ping m atrix. If the tangent dam ping m atrix m odel is applied then
the increm ental m ethod, the dam ping forces at the end of the step are the dam ping forces at the beginning of
the step plus the increm ent caused by the tangent dam ping m atrix m ultiplied by the increm ent in the velocities.

The problem noted where the tangent damping m atrix is derived from the tangent stiffness m atrices is that if the
structure exhibits hysteresis then so does the dam ping. This m eans that when the velocity of the structure goes
to zero at the end of the earthquake the dam ping forces do not go to zero but one is left with residual due to the
perm anent plastic deform ations in the m em bers.

In the early versions of Ruaum oko the dam ping forces at each tim e step were com puted using the dam ping m atrix
as a secant m atrix. It was also used as the tangent m atrix in the increm ental equations of equilibrium . W hen this
m is-interpretation was corrected in 2002 so that the m atrix was used strictly as a tangent dam ping m atrix there
was an outcry from som e users who found that their results were different from those obtained earlier.

Another interpretation is that the current dam ping forces are the product of the Rayleigh dam ping m atrix, using
the tangent stiffness m atrices, tim es the current velocity vector. This im plies that the dam ping m atrix is being
interpreted as a secant dam ping m atrix. In this case there are difficulties in defining the tangent dam ping m atrix
to use in the equation of increm ental equilibrium . New options have been added to the program to allow the user
to use the Rayleigh tangent stiffness dam ping as either a tangent dam ping m odel (the default tangent dam ping
m odel) or as a secant dam ping m odel which was then way the dam ping was set up in Ruaum oko prior to 2002.
If the initial stiffness Rayleigh dam ping m odel is used or the W ilson-Penzien dam ping m odels are used then the
dam ping is constant and there are no differences between the initial, tangent or secant damping m atrices

4.4 Recommendation

It is recom m ended that where practical, or until better inform ation is available, a uniform dam ping should be
specified in all m odes. This is ICTYPE = 2 with the fraction of critical dam ping specified at the two m odes be the
sam e.

If a Rayleigh or Proportional dam ping m odel is used where the frequencies at which dam ping is specified are such
that the highest m odes of free vibration are at least sub-critically dam ped.

It would also appear reasonable that the tangent stiffness m atrix is a better choice than the initial elastic stiffness
as with a non-changing dam ping as the structures reduces its stiffness as inelastic effects takes place im plies that
the fractions of critical dam ping increase as the natural period lengthens. However, as discussed above, the
tangent dam ping m atrix m odel using the tangent stiffness m atrix that when the stiffness m atrix exhibits hysteresis
then so does the tangent dam ping m atrix. This im plies that when the velocities go to zero the dam ping forces
m ay be non-zero. For this reason it is suggested that the tangent stiffness m atrices be used to contribute to a
Secant dam ping m atrix i.e. ICTYPE = 6. (This was what ICTYPE = 1 im plied until 2002)

14
 Figure 8. Pacoima Dam Accelerogram (1971 San Fernado Earthquake)

Figure 9. Displacement Response Spectra for the Pacoima Dam Accelerogram

15
Figure10. Displacements at the roof of the 12 storey due to the Pacoima Dam Accelerogram

Figure 11. Damping M oments at Central Joint Level 1

16
 Figure 12. Horizontal Damping Forces at Level 1

Figure 13. Relative Horizontal Inertia Forces at Level 1

17
5. STRUCTURAL MEMBERS
The program has different m em ber m odels to represent the stiffness of the structure. These fall into
several categories, Fram e, Spring, Dashpot, Tendon, Contact, Quadrilateral, Masonry Panel and Ground
or Foundation m em bers. The two-dim ensional program also has a reinforced concrete wall m em ber.

Figure 14 Frame M ember

5.1 Frame M embers

The Fram e m em ber type covers the beam and beam -colum n m em bers. A beam m em ber is a general three
dim ensional m em ber which m ay use alm ost any of the hysteresis rules governing the behaviour of the plastic
hinges that m ay form at each end of the m em ber. A beam m em ber m ay also have a bi-linear axial load - axial
displacem ent hysteresis. However, there is no interaction between the axial yield states and those associated
with the m om ent-curvature yield states. A beam -colum n m em ber differs from a beam m em ber in that the axial
force in the m em ber affects the current yield m om ents at each end or the m em ber. There are three axial load -
bending m om ent interactions built into the program , one for reinforced concrete colum ns, one for steel
colum ns and one for a m ore general colum n. In the two-dim ensional program the four nodes I, J, K and L lie
in the global X-Y plane and node M is not used.

The inelastic behaviour of a beam and beam -colum n m em ber, in general, follows the concept of the Giberson
one-com ponent m odel [Sharpe, 1974] which has a plastic hinge possible at one or both ends of the elastic
central length of the m em ber.

Rigid end-blocks m ay be incorporated within the length of any of the Fram e m em bers. If there are joint
flexibilities or shear deform ations, the m em ber stiffness is inverted to get the m em ber flexibility, the joint and
shear flexibilities are added and the resulting m atrix is again inverted to get the final stiffness of the beam
m em ber.

Figure 15 Rigid End-blocks

18
 Figure 16 Giberson One Com ponent Beam M odel

The stiffness of the hinge is controlled by the tangent stiffness of the current point on the appropriate hysteresis
rule.

Figure 17 Giberson Hinge M odel

The stiffness of the hinge is such that the rotation of the hinge together with the rotation associated with the
elastic curvature of the beam over the hinge length is the sam e as the rotation associated with the curvature
over the hinge length with the inelastic properties in the hinge zone. If the hinge is in the elastic range the
plastic hinge has an infinite stiffness. The stiffness of the spring hinge for a hinge length of H, curvature N and
the inelastic m om ent-curvature relationship is M = f EI N where f < 1 is

19
 Figure 18 Tw o Com ponent Beam M odel

An alternative beam m em ber is the two-com ponent beam [Kanaan 1973] where two m em bers in parallel
represent the behaviour of the m em ber. One m em ber is elastic and the second is elastic or has a perfect hinge
at one or both ends of the m em ber. Traditionally, this m em ber could only represent a bi-linear hysteresis rule
but the m em ber form ulation has been generalised so that it can follow m ost hysteresis rules.

Figure 19 Variable Flexibility Beam M odel

Another beam m em ber is one in which the inelastic behaviour is spread along the m em ber hinge length. The
yielding zone has a flexibility which varies parabolically from the inner elastic zone to a m axim um flexibility at
the m em ber ends. This m em ber cannot be used to m odel perfectly plastic behaviour as the flexibility becom es
infinite at the ends of the m em ber.

A final form of fram e m em ber available only in the two-dim ensional program is the Four-Hinge beam m em ber
which can allow for two plastic hinges within the span of the m em ber in addition to the two hinges at its ends.
The two outer sub-m em bers are Giberson one-com ponent beam s and the inner sub-m em ber is a fully elastic
beam . The beam m ay be used to m odel gravity dominated beam s where under seism ic loading in one
direction yielding occurs at one end hinge and at the interior hinge near the other end of the beam while under
reversed loading yielding occurs at the other two hinges. The hinges generally undergo yield in one direction
only. This beam m ay also be used to represent a haunched m em ber with the hinges form ing at the interior
ends of the haunches. This is achieved by giving the inner beam a fraction of the outer com ponent stiffnesses
and by m aking the end hinges very strong or by setting both end yield m om ents to zero (default elastic
behaviour). If shear deform ations are specified it is assum ed that both the shear area and m om ent of inertia
of the central section have the sam e stiffness reduction factor when com pared with the two end sections. If
the fram e m em ber is linear elastic then all the different beam and beam -colum n m em bers are identical in their
behaviour.

Figure 20. 4 Hinge Beam

20
5.2 Spring M embers

Figure 21. Spring M ember

Spring m em bers m ay be used to m odel special effects in the structure. In two-dim ensional structural analyses
they can be used to represent m em bers acting out of the plane of a fram e but representing forces that act in
the plane of the fram e. An exam ple of the latter is a rotational spring representing the torsional behaviour of
a beam oriented perpendicular to the plane of the fram e and connecting it to an adjacent parallel fram e. The
spring m em ber orientation is given by the axial orientation of the m em ber but if the two end nodes coincide
resulting in a zero length m em ber then the longitudinal and transverse directions coincide with the structure,
or global, X, Y and Z axes respectively. In the two-dim ensional program the four nodes I, J, K and L lie in the
global X-Y plane and node M is not used.

In the three dim ensional program the spring m em ber m ay have a longitudinal spring, two transverse springs,
a torsional spring and two rotational springs. In the two-dim ensional program there is only the longitudinal and
transverse springs and the rotational spring about the local z axis The force in the springs are proportional
to the differences in the longitudinal and transverse displacem ents of the two ends. The rotational spring
m om ents are only proportional to the differences in the rotations at each end of the m em ber. If the end nodes
are coincident then the transverse rotational com ponents behave like the torsional clock spring. This m em ber
m ay be thought of as a generalised Truss m em ber which m ay follow any of the hysteresis rules. There is no
interaction between the yield behaviour of the longitudinal, transverse and rotational actions.

A second version differs from the first in that there is an elliptic interaction between the transverse yield forces
and the transverse m em ber behaviour is represented by a three-com ponent spring and therefore follows a tri-
linear hysteresis rule. The longitudinal and rotational com ponents follow a bi-linear hysteresis. In two-
dim ensional analyses this m ay be used when m odelling a bridge pier when the plane of the analysis is that of
the bridge deck.

A third variant is sim ilar to the first spring m em ber except that the transverse or shear behaviour follows a
m odified SINA hysteresis rule and the yield forces in the transverse direction are also a function of the
associated rotational spring ductility. This m em ber is designed to m odel beam -end hinges where there is
possibility of a shear failure following yield in flexure. This is particularly useful in m odelling fram es designed
to earlier building codes where capacity design philosophies were not in use.

21
5.3 Damping or Dash-pot M embers

Figure 22. Damping or Dash-pot M embers

Dam ping m em bers m ay be used in the structure to represent the actions of local viscous energy dissipaters
that m ay exist in the structure. The dam ping m em ber is sim ilar to an elastic spring m em ber in that it has up
to six dam ping actions, a displacem ent action in the longitudinal direction and the two transverse directions
and three rotational actions. These m em bers are only used in the tim e-history analysis and contribute to the
dam ping m atrix of the structure. If the m em ber length is zero the longitudinal and transverse directions coincide
with the structures global X, Y and Z axes. The m em ber has been extended to allow for a non-linear force-
velocity relationship. In the two-dim ensional program the four nodes I, J, K and L lie in the global X-Y plane
and node M is not used and the dam per actions are sim ilar to the two-dim ensional spring m em ber.

5.4 Constant-Force and Active-Tendon M embers

Figure 23. Tendon M ember

These m em bers have no stiffness properties but are used to apply forces to the structure. In the Constant-
Force m em bers the forces acting on the joints at each end of the m em ber are a function of the displacem ents
between the joints and the direction of the change in the m em ber deform ation. The m em ber is like a truss
m em ber in that it carries only an axial force. If the m em ber is of zero length the m em ber local x axis is in the
direction of the global X axis. In the two-dim ensional program the four nodes I, J, K and L lie in the global X-Y
plane and node M is not used.

The Active Tendon m em ber is sim ilar to the Constant-Force m em ber but the force is a function of the
displacem ents, velocities or accelerations of specified nodes in the structure. There is provision to apply a
tim e-delay in the response of the tendon. These m em bers m ay be used to m odel sim ple active control system s
in the structure.

22
5.5 Contact M embers

Figure 24 Contact M embers

These m em bers were incorporated in RUAUMOKO to represent the behaviour of m em bers that m odel pounding
between buildings during earthquakes as well as a foundation-soil rocking interaction. The m em ber has both
stiffness and dam ping actions where the dam ping coefficient is a function of the current stiffness of the contact
m em ber. There is also provision to apply friction forces in the directions perpendicular to that of the contact
m em ber axis. If the m em ber is of zero length the contact is assum ed to act in the global X axis direction. In the
two-dim ensional program the nodes I, J, K and L lie in the global X-Y plane and node M is not used. The local
x-y plane also lies in the global X-Y plane.

23
5.6 Quadrilateral Finite Elem ents

Figure 25 Quadrilateral Finite Elem ents

A Hybrid Stress Type II quadrilateral finite elem ent has been incorporated into the program to allow for the
m odelling of in-fill panels and to allow for foundation m odelling, particularly if coupling effects between adjacent
foundations is required. The elem ent assum es a cubic variation of the x, y and shear stresses over the elem ent.
The elem ent edges have a cubic variation of norm al displacem ent and a linear variation of the tangential
displacem ent along each edge. This m eans that the edge displacem ents are com patible with any adjacent beam
m em bers. A nine point Gaussian quadrature is used to form the elem ent stiffness and a three point Gaussian
integration is used along each elem ent edge. This m em ber is, at present, only linearly elastic. Either plane stress
or plane strain m aterial m odels m ay be selected.

This elem ent also has available a plate-bending action, also based on a Hybrid-Stress form ulation so that plates
or shells m ay be m odelled. The elem ent m ay be used to m odel walls or floor slabs in a fram ed structure.

All four nodal points m ust be distinct, i.e. triangles are not perm itted. The nodal points m ust be num bered in an
anti-clockwise sequence around the elem ent. The direction determ ines the direction of the local z axis and hence
the sign of the stresses and bending m om ents in the elem ent.

In the two-dim ensional program node I, J, K and L lie in the global X-Y plane and only the plane stress and plane
strain options exist in the elem ent properties.

24
5.7 M asonry Panel Elem ents

Figure 26 Truss M echanism

The four-node m asonry panel elem ents proposed by Crisafulli [Crisafulli, 1997] are designed to represent the
behaviour of m asonry in-fill panels which are surrounded by reinforced concrete or steel fram e m em bers. Each
panel is represented by five strut m em bers, two parallel struts in each diagonal direction and a single strut acting
across two opposite diagonal corners to carry the shear from the top to the bottom of the panel. This last strut
acts across the diagonal which would be in com pression and so connects different top and bottom corners
depending ion the deform ation of the panel. The first four struts use the m asonry strut hysteresis rule developed
by Crisafulli and the fifth, or shear, strut uses a bi-linear hysteresis rule. The concept of the two parallel struts
across each diagonal is to represent the rotational effects on the joints of the com pression forces carried across
the diagonal of the panel.

An elastic plate bending action m ay also be considered as part of the stiffness in this elem ent. The elem ent is
assum ed to be near rectangular in shape and that the local or elem ent y axis is m eant to be in the vertically
upward direction.

All four nodal points m ust be distinct, i.e. triangles are not perm itted. The nodal points m ust be num bered in an
anti-clockwise sequence around the elem ent.

In the two-dim ensional program node I, J, K and L lie in the global X-Y plane.

25
5.8 Foundation or Ground Elem ents

Figure 27 Foundation or Ground Elem ents

These elem ents developed by Cham bers [Cham bers 1998] and extended by Rahm an [Rahm an 1998] are beam -
like m em bers designed to represent sim ple soil-structure interaction effects. These m em bers m ay be thought
of as a distributed W inkler spring m odel. There are several different representations of the stiffness, dam ping
and m ass properties of the elem ent. At the present tim e these m em bers have only stiffness in the local x-y plane.
In the two-dim ensional program the nodes I, J, K and L lie in the global X-Y plane and node M is not used. The
local x-y plane also lies in the global X-Y plane.

26
5.9 Structural-W all M em bers (Tw o-dimensional Ruaumoko-2D only)

Figure 28 Structural Wall M ember

The structural-wall m em ber was developed as the Taylor W all-A elem ent [Taylor 1977] to represent the
behaviour of reinforced concrete walls. The m em ber cross-sectional area and second m om ent of area are
num erically integrated across the wall section using the current steel and concrete m odulii. As a result the m odel
allows for the shift of the neutral axis position due to the changing axial load and bending mom ent. The initial
position of the neutral axis is assum ed to be that obtained from the uncracked section. The m em ber is
com putationally expensive in that sm aller than norm al tim e-steps and Newton-Raphson iteration at every tim e
step is usually required to m aintain satisfactory equilibrium . Taylor also often used several elem ents to represent
a single storey. As a result, for m ost analyses, structural-walls have been represented by beam -colum n
m em bers with shear deform ations included.

The integration of the stiffness along the m em ber length is accom plished using a Lobatto integration instead of
the original Sim pson's Rule integration. The num ber of sections m ay be specified from 3 to 7. The properties of
each section is evaluated by assessing the stresses and stiffnesses of a num ber of segm ents across the section.
The num ber of segm ents, or filam ents, m ust be between 3 and 20. As the sections are assum ed to be initially
uncracked the stiffness of the m em ber m ay be unrepresentative of the actual section because som e cracking
will be present due to shrinkage or earlier excitations. To allow for these reductions of stiffness, a factor to lim it
the m axim um fraction of the initial flexural stiffness is provided. This factor will enable the natural frequencies
of free-vibration of the initial structure to take m ore realistic values than those associated with the uncracked
structure.

The original Taylor elem ent used a very sim ple concrete stress-strain rule and this has now been extended to
include the rule of Kent and Park [Kent 1971, Park 1982, Dodd,1992] which has a m ore realistic stress-strain law
and allow for a better representation of hysteresis in the concrete. Taylor also used a bi-linear stress-strain law
for the steel and the Kent and Park m odel uses a Bounded Surface rule [Zhu 1995] for the steel. This is a sim pler
rule than the Ram berg-Osgood functions used by Kent and Park. The first plastic excursion is bi-linear but in
subsequent cycles the initial yield is at half the input steel yield stress and the bi-linear skeleton provides the
plastic bounding surface.

There is a special version of this m em ber designated by having only 2 sections to represent a Giberson like
beam -colum n with Taylor wall-type hinge sections at each end and an elastic region between them .

27
5.10 Five Node Definition of One Dimensional and Tw o Dimensional M embers

Figure 29 Five Node M ember

All m em bers except the quadrilateral finite elem ents and the m asonry panel elem ents are defined by five nodal
points. The two outer nodes are the usual nodes where the m em ber forces and stiffnesses act and the inner two
nodes are used to define rigid links connecting the deform able part of the m em ber to the outer nodes. If the
inner nodes are not defined, or are zero, they are taken as the sam e as the outer nodes and there are no rigid
links. The aim of this definition is to enable m odelling of com plex structural geom etries without having to resort
to artificial very stiff m em bers to arrange the interconnection of m em bers. These artificial very stiff m em bers run
the risk of destroying the accuracy of the total stiffness m atrix besides m arkedly increasing the size of the total
stiffness m atrix. If artificial m em bers are used the interior nodes have their own degrees of freedom , increasing
the total num ber of degrees of freedom and the artificial m em bers, often with stiffnesses m any orders of
m agnitude greater than those of the deform able m em bers in the structure, control the significance of the
stiffnesses in a com puter system carrying only a lim ited num ber of significant digits. W ith the five-node definition
the inner nodes do not have any degrees of freedom and the displacem ents of the inner nodes are rigidly linked
to the displacem ents and rotations of the outer, or real, nodes. The fifth node defines a plane through nodes K,
L and M which defines the plane containing the m ajor principal z axis of the m em ber. The local axes have their
origin at node K; the local x axis lies along the m em ber, the local z axis lies on the plane of nodes K, L and M
and is perpendicular to the axis of the m em ber and lies on the sam e side of the x axis as does node M . The local
y axis is then perpendicular to the local x and z axes. The quadrilateral and panel elem ents differ in having only
four nodal points, i.e. node M is zero.

In the two-dim ensional program the nodes I, J, K and L lie in the global X-Y plane and node M is not used. The
local x-y plane also lies in the global X-Y plane in the two-dim ensional analyses.

28
 Figure 30. Quadrilateral Finite Element

The quadrilateral elem ents and the m asonry panel elem ent are four node elem ents (triangles are not perm itted)
and the four nodes m ust be in an anti-clockwise (counter-clockwise) sequence around the elem ent. The m asonry
panel elem ents are presum ed to be rectangular or near rectangular in shape and that the local y axis is in the
vertical direction.

5.11 Stiffness Matrix

The final stiffness m atrix is stored as a colum n-stored sky-line m atrix. As the m atrix is sym m etric only the
diagonal and above diagonal term s are stored. During the tim e-history analysis the m atrix is updated with the
changes in the m em ber stiffness m atrices. The m em ber data-base for each m em ber retains a copy of the latest
m em ber tangent stiffness m atrix. The equations are autom atically renum bered using an algorithm by Sloan to
optim ise the storage and equation solving speed. The equilibrium equations are solved by a sky-line equation
solver using the LDU theorem approach and is developed from the equation solver described by W ilson and
Dovey [W ilson 1978]. If necessary Newton Raphson iteration m ay be used at each tim e-step to elim inate residual
forces resulting from the change in m em ber stiffnesses during the tim e-step. This iteration is controlled by the
param eters MAXIT and FTEST. If MAXIT = 0 then no iteration is allowed. MAXIT would norm ally be set to the
order of 5 cycles if iteration is enabled. FTEST represents the ratio of the squares of the norm s of the residual
force vector and the increm ental force vector at the tim e step. FTEST = 0.01 im plies a 10% average error and
FTEST = 0.001 im plies a 3% average error. Any residual force vector rem aining at the end of the iteration is
added to the next increm ent of force vector in an im plied self-correcting procedure.

Statistics on the num bers of iterations perform ed and the num ber of tim es the stiffness m atrix of the structure
is updated during the tim e history is provided at the end of the output file. If the structure is non-linear while
com puting the solution to the static loads, a m axim um of 5 cycles of Newton Raphson iteration is carried out.
The num ber of iterations required is output with the static solution.

29
6 STIFFNESS AND STRENGTH DEGRADATION
6.1 Hysteresis Rules for Stiffness Degradation

Many different hysteresis rules have been incorporated in RUAUMOKO to represent the inelastic behaviour of
Fram e and Spring m em bers. They range from the sim ple elasto-plastic and bi-linear rules, the com putationally
m ore expensive Ram berg-Osgood rule [Sharpe 1974] to rules such as those developed by W ayne Stewart
[Stewart 1987] which requires over thirty param eters to keep track of the current stiffness.

Figure 31 Elasto-plastic and Bi-linear Hysteresis Rules

Figure 32. Ramberg-Osgood Hysteresis Rule

30
The bi-linear with slackness m odel shown in Figure 28 can be used to represent diagonal braced system s where
yield in one direction m ay stretch the m em bers leading to a slackness in the bracing system . The pinching m odel
of Kivell [Kivell 1981] shown in Figure 29 was designed to represent the behaviour of the nails in steel nail-plate
units connecting tim ber m em bers together at the joints.

The m ajority of the degrading rules have been developed to represent the behaviour of reinforced concrete
m em bers. The sim plest rule is the Clough Degrading Stiffness which m ay be regarded as a sub-set of the
Modified Takeda hysteresis rule [Otani 1974]. Exam ples of these rules are shown in Figure 30 to 36.

Figure 33. Bi-linear w ith Slackness Hysteresis Rule

Figure 34 Kivell Pinching Hysteresis Rule

31
Figure 35. M odified Takeda Degrading Stiffness Hysteresis Rule

Figure 36. Origin Centred Stiffness Hysteresis Rule

Figure 37. SINA Degrading Stiffness Hysteresis Rule

32
Figure 38. Degrading Bi-linear Hysteresis Rule

Figure 39. M utos Degrading Stiffness Hysteresis Rule

Figure 40. Fukada Hysteresis Rule

33
 Figure 41. M ehran Keshavarzians Degrading Hysteresis Rule

Li Xinrong [Li Xinrong 1995] has developed a m odel which allows for the changes in the stiffness of reinforced
concrete colum ns as the axial force in the colum n changes. This is shown in Figure 37.

Figure 42. Li Xinrong Reinforced Concrete Column Hysteresis Rule

34
The very general rule developed by Wayne Stewart [Stewart 1987] shown in Figure 43 was initially developed
to model nailed-plywood sheathed structural walls but has also been successfully used to model reinforced
concrete columns with plain round bar reinforcement [Liu,2001].

Figure 43. W ayne Stew arts Degrading Stiffness Hysteresis Rule

The non-linear elastic model shown in Figure 44 represents the non-linear behaviour of face-loaded masonry
wall units. By selecting suitable parameters other systems may also be modelled. A similar model has been
proposed by Widodo [Widodo 1995] to represent foundation compliance springs. Another non-linear elastic
rule follows a bi-linear yielding relationship between force and deformation but unloads back along the same
path without exhibiting any energy dissipation.

Figure 44. Non-linear Elastic Rule

35
The Hertzian Contact rule [Davis 1992] shown in Figure 45 is useful for modelling the contact between
impacting structures.

Figure 45 Hertzian Contact Spring

A form of hysteresis shown in Figure 46 which gives a smooth transition in the stiffness as the deformation
changes is exhibited by the Bouc hysteresis rule [Wen 1976]. This rule has been used to represent lead-rubber
bridge bearings [Bessasson 1993] and has also been used to represent the behaviour of inelastic structures
in random vibration studies of buildings [Baber 1981].

Figure 46 Bouc Hysteresis Rule

The Ring-Spring model [Hill 1994] shown in Figure 47represents the non-linear behaviour of certain frictional
hysteretic energy dissipation devices which are designed to provide a form of base-isolation under earthquake
excitation.

Figure 47. Ring-Spring Hysteresis

36
6.2 Strength Degradation

To allow for a strength degradation the yield levels in the interaction diagrams may be reduced as either a
function of the ductility or the number of load reversals from the backbone or spine curve of the hysteresis rule.
Figure 48 gives an illustration of this concept.

Figure 48 Degrading Strength Rule

This has been extended recently to allow for a tri-linear degradation of strength with ductility or cycle number.
It m ust be noted that in RUAUMOKO it not possible to have the strength reduce to zero. If any action has both
positive and negative yield actions equal to zero, the action is assum ed to be elastic. This m eans that the action
has infinite yield strengths. Therefore, if the strength was allowed to reduce to zero, degradation would
progressively occur until it reached zero strength when the m em ber would suddenly act as an elastic m em ber.
A 1% strength is close enough to zero for engineering purposes.

37
7 APPLIED LOADS
7.1 Static Loads.

Static loads m ay be input as nodal loads and/or as m em ber loads. If Fram e m em bers are loaded then the
m em ber loads, covered as part of the section data, should be applied as this will give the correct m om ents at the
ends of the m em bers ensuring that the yield interaction diagram s are working with the total m om ent acting in the
m em bers at that point. T he nodal loads can also represent the loads com ing from the colum ns and from
m em bers oriented perpendicular to the fram e. It m ust be noted that the applied loads do not contribute to the
m ass m atrix and that the self-weights do not contribute to the static loads on the structure. The static analysis
is perform ed before the m odal analysis so that the effects of the axial forces acting in the colum ns can be taken
into account in the m odal analysis. The static analysis is the starting point for the dynam ic analysis as this
ensures that all m em bers start with the correct force distribution before com m encing the tim e-history analysis.

7.2 Earthquake Ground Acceleration Excitation.

The dynam ic excitation is applied in term s of a ground acceleration history applied to all fixed X, Y or Z
displacem ent degrees of freedom , depending whether a one, two or three com ponent excitation is being applied.
All earthquake accelerogram s are assum ed to be input in units of the acceleration of gravity. To get the
acceleration value to excite the structure the accelerogram is internally m ultiplied by the acceleration of gravity.
In the default form of analysis, the displacem ents, velocities and accelerations are relative displacem ents, relative
velocities and relative accelerations. Total accelerations, velocities and displacem ents can be generated by the
post-processing program DYNAPLOT.

If a travelling wave input is being used, the wave delay tim e at each support node is com puted using the
coordinates of the node and the wave velocities in the global directions. The node with the first arrival tim e is
identified and it is assum ed that the m otion arrives at this point at tim e t=0.0. Delay tim es are then com puted for
all other support nodes. At each tim e step the ground velocities and displacem ents are integrated from the
ground acceleration records taking into account the appropriate tim e delays using a linear variation of
acceleration from tim e-step to tim e-step in the input record. The displacem ents, velocities and accelerations
com puted by the program are total displacem ents, velocities and accelerations. Relative accelerations, velocities
and displacem ents m ay be obtained using DYNAPLOT. It m ust noted that m any accelerogram s do not start from
'at rest' conditions and if the initial velocity, and displacem ent, are known then they should be input, this will tend
to prevent the displacem ents of the structure linearly increasing with tim e if the initial velocity is non-zero. It is
now possible to apply a random dispersion contribution to the acceleration history applied to the nodes receiving
the delayed input. The dispersion is a function of the delay tim e.

7.3 Earthquake Ground Displacement Excitation.

The dynam ic excitation is applied in term s of ground displacem ent histories applied at specified nodal degrees
of freedom . The num ber of different ground displacem ent histories depends on user input. The input histories
have the sam e input form ats as the above ground acceleration histories. The displacem ents used in the
analyses is the sam e total displacem ent form ulation used in the travelling wave analyses described above.

7.4 Dynamic Force Excitation

Loads m ay be applied to the structure as one, two or three load patterns each of which is m ultiplied by its own
load tim e-history. These tim e-histories are input using the sam e form ats as are used for the earthquake ground
acceleration records but in this case these tim e-histories are m ultipliers of the forces in the load pattern, or load
shape, vector.

7.5 Active-Tendon Loading

Loads m ay applied to parts of the structure by the Tendon m em bers. In the constant force m em ber the force
in the tendon is a function of the displacem ent and velocity in the m em ber. In the active tendon m em ber the force
is governed by com binations of the accelerations, velocities and displacem ents of the structure. A tim e-delay
m ay be im posed on the response of the active tendon. This m em ber m ay be used to m odel sim ple active control
m echanism s.

38
7.6 Pushover Analysis

A pushover analysis m ay be achieved by using the Dynam ic Force Excitation using a slow ram p loading function.
The load should be applied slowly enough that inertia forces are insignificant. If the m axim um load exceeds the
total capacity of the structure the analysis m ay becom e unstable. The m ass can be om itted in the pushover
analyses but the inertia m ay be all that retains analysis stability if the m axim um strength is exceeded in the
structure, or at a joint, and an elasto-plastic m odel is being used.

7.7 Adaptive Pushover

In the norm al pushover analysis a given lateral load pattern is slowly increased until a point is reached where the
lateral resistance is largely that of the inertia of the structure. The m ajor difficulty is to assess how m uch to
increase the load without causing the analysis to fail because the load has exceeded the capacity of the structure.

Another difficulty with the norm al pushover analysis is the loading distribution applied to the structure. Many
analysts take the seism ic code equivalent static or first m ode loading pattern but the difficulty is that the capacity
of the structure is reflected in the loading pattern used and m any engineers are not convinced that the seism ic
code loading pattern is appropriate for a fram e structure in its ultim ate state as the forces on a real structure in
an earthquake are functions of the accelerations of the structure and m ass distribution of the structure..

Figure 49 shows a structure subjected to a variety of appropriate pushover loading patterns and Figure 50 shows
the results of the subsequent pushover tests when these loads are increased.

As part of the tools being developed for the assessm ent of structures built to earlier seism ic codes Satyarno
[Satyarno 1998,1999] suggested an adaptive pushover analysis where the loading pattern reflects the
deform ation pattern of the structure and where the analysis autom atically term inates when the capacity of the
structure is reached. This m ethod has also shown itself to be independent of the initial choice of loading pattern
except that the pattern chosen does influence the num ber of steps required to reach the structures capacity.

Figure 51 shows the results of the adaptive pushover analysis when com pared with the standard pushover
analysis. As shown the final ultim ate, using the analysis term ination process described later in this section is
independent of the choice of loading pattern. The loading pattern adjusts itself to the deform ation of the structure.

The analysis starts by taking the loading pattern described in the SHAPE section of the m anual. This is identical
to the starting point for a norm al push-over analysis except that instead of this pattern of loading being m ultiplied
by a tim e-like function the load pattern is m ultiplied by the factor " where

where DT and TIME are described in line 3 of the input data. The factor 2 above m ay be altered by supplying
a num ber greater than 2.0 following the word SHAPE described later in the data. The deflection reached by the
structure will be, with the 2 above, reach twice the elastic deflection caused by the loads specified in the SHAPE
loading distribution.

At each step, after the initial step, a Modified Rayleigh Method process is used to estim ate the tangent
fundam ental frequency of the structure.
If R is the displacem ent during the past increm ent due to increm ental forces {g}

ie

where is the current tangent stiffness m atrix.

From the equation of free vibration

39
where T is the current tangent fundam ental natural frequency and [M] is the m ass m atrix and {N} is a m ode
shape of free vibration.

Let {R} be an estim ate of the m ode shape.

ie

and

Note:

For the next step

so the new increm ental load vector is a function of the mass, the equivalent frequency and the displaced shape
of the structure. The increm ent is norm alized so that the m agnitude of the increm ent of displacem ent is sim ilar
to that of the first step.

During the pushover analysis dam ping is ignored and the m ass is only used to com pute the increm ental loads.

The analysis term inates when

(1) T 2 is less than 10 -6 T 2 at the first step
(2) The Newton Raphson iteration is not achieved within the m axim um num ber of cycles specified
in MAXIT
(3) The stiffness m atrices becom e singular.
(4) The specified m axim um structure displacem ent is reached

As the analysis is now unlikely to reach the duration TIME the post-processor program DYNAPLOT has been
m odified to check the actual duration of the post-processor inform ation and to reset the duration used within
DYNAPLOT.

Figure 49. Pushover Loading Patterns

40
 Figure 50. Conventional Pushover Results

Figure 51. Adaptive Pushover Versus Conventional Pushover

41
7.8 Cyclic Adaptive Push-Over Analysis.

The adaptive push-over has been extended to allow for a cyclic push-over which follows an adaptive forcing
pattern for each part of the loading cycle. A displacem ent history is supplied for a specified displacem ent degrees
of freedom at a specified node. The load increm ent is scaled to generate the total nodal displacem ent in the
history over approxim ately 90% of the tim e-steps specified in the input data. The loading history starts the sam e
way as in the norm al adaptive push-over with the loading distribution changing as the structures stiffness
changes. Once the displacem ent at a peak in the displacem ent history is reached, the loading direction is
reversed and the loading pattern again starts with the initial input loading shape. This force distribution is justified
in that the structure is likely to be near its elastic stiffness as the unloading process com m ences and the force
distribution should be sim ilar the forces at the start of the loading with the initial elastic structure.

42
8 M ODAL ANALYSIS

The program m ay carry out a m odal analysis even though the results are not generally used during the dynam ic
analysis. A m odal analysis does provide a check on the structural data in that the user can check that the natural
frequencies and m ode shapes are what would be expected for such a structure. In som e cases a m odal analysis
is necessary as the natural frequencies of free vibration, and in som e cases the m ode shapes, are used to
generate the appropriate dam ping m atrix for the structure.

Anim ated representations of the m odes shapes m ay be displayed on the com puter screen if desired.

Taking the equation of undam ped free vibration, where no loads are assum ed to act upon the structure, the N
degree-of-freedom equation of equilibrium becom es

and assum ing sim ple harm onic m otion {u} = {M} iY isinT it then the equation of free-vibration sim plifies to

where {M} i and T i are the ith m ode and frequency of free vibration respectively.

The N vectors {M} i form a Basis set of vectors in that any vector in the N dim ensional space m ay be represented
as a com bination of the m ode shapes

where {Y} are the m odal am plitudes and [M] is the m odal m atrix in which each colum n is a m ode shape.

Substituting this into the equation of equilibrium and pre-m ultiplying by [M]T gives

where

From the properties of orthogonality of the m ode shapes it can be shown that [M *], [C *] and [K *] are diagonal
m atrices with

Thus for each m ode

The system is now represented as N uncoupled single degree-of-freedom system s.

43
Dividing through by M i* the second order ordinary differential equation is obtained for each m ode i as

The term PF i is called the Participation Factor for the ith m ode and it is an indicator of how m uch the ith m ode
is excited by the ground acceleration in the direction of the earthquake and indicates the im portance of the
contribution of the ith m ode to the displacem ents of the structure. It should be noted that the num erical
m agnitude of the Participation Factors depends on the type of norm alization used for the m ode shapes.

Once the Y i are found then the relative structural displacem ents are found from

and the effects of the choice of norm alization of the m ode shapes is cancelled out.

In a m odal Response Spectrum analysis the Base Shear V i in the ith m ode of a structure can be obtained from
the Spectral Acceleration S A [Carr 1994] using the following equation.

The Effective W eight of the ith m ode indicates the im portance of the contribution of the ith m ode to the total base
shear acting on the structure in the sam e way that the Participation Factor shows the contribution of the ith m ode
to the displacem ents of the structure. The num ber of m odes required in a m odal analysis is specified in m any
codes to be such that the sum of the Effective W eights of the m odes used m ust be at least of the order of 90%
of the total weight of the structure.

In RUAUMOKO the m odal analysis is norm ally perform ed after carrying out the static analysis as this allows, in
P-Delta and large displacem ent analyses, for the adjustm ent of the m em ber stiffnesses of fram e m em bers that
have axial loads in them . Com pressive forces will lead to a geom etric stiffness term s that reduce the stiffness
of the m em bers. This m eans that in m ulti-storey fram es the lateral stiffness of the structure m ore accurately
represents the real structure with gravity acting upon it.

8.1 Reduction of Eigenvalue Problem for Degrees of Freedom W ithout M ass

In RUAUMOKO m any of the degrees of freedom m ay not have m ass and this requires a static condensation
[Clough and Penzien 1992] process to rem ove these dependent degrees of freedom from the system . However,
a static condensation at the structure level is a very expensive procedure and in RUAUMOKO this has been
achieved by using a condensed flexibility approach first used by the author for thin shell analysis [Carr 1967]. This
m ethod does not require rearrangem ent of the stiffness m atrix but uses a static analysis approach.

For a standard static condensation

where {N 1} are the m ode shape associated with degrees of freedom with m ass and {N 2} are the parts of the m ode
shape associated with m ass-less static degrees of freedom .

From the second equation

Sub

44
stituting into the first equation gives

Once the m ode shape and natural frequency are com puted the rem aining term s in the m ode shape
are obtained from

The disadvantage of this approach is that the stiffness matrix of the structure has to be rearranged and although
the com putation of can avoid the com putation and inversion of what m ay be a large m atrix by using
a backward Gauss-elim ination this is still an expensive step [Sharpe 1974].

Using a m ethod used by the author for dynam ic analysis of thin shells [Carr 1967] starts by setting up unit load
vectors for each degree of freedom that has m ass. By selecting the displacem ents for each degree of freedom
that has m ass from the flexibility vector for each of these load cases a condensed flexibility m atrix is com puted.

The equation of free vibration can now be written as

The change of variable

and after substituting and then pre-m ultiplying by (note is a sym m etric m atrix) leads to the eigenvalue
problem with a sym m etric m atrix. If is a diagonal m atrix this is very easily achieved.

W hen the eigenvectors have been com puted the part of the node shape associated with degrees of freedom
having m ass is obtained.

Using this approach has the advantage that the natural frequencies and m ode shape are found m ost
accurately for the lowest natural frequencies rather than for the highest frequencies which occur when the norm al
stiffness form ulations are used. The eigenvalues are now the squares of the inverse frequencies and not the
squares of the frequencies and it m ust be noted that m ost eigenvalue algorithm s find the largest eigenvalues with
greatest relative precision. Once the m ode shapes for the degrees of freedom having m ass are com puted the
whole m ode shape is com puted from the equivalent of

This m ethod has the advantage that the actual degrees of freedom do not need re-arranging and the skyline form
of the stiffness m atrix is retained.

45
9 TIME-HISTORY INTEGRATION
9.1 New mark Constant Average Acceleration M ethod

The dynam ic equation of equilibrium is integrated by the unconditionally stable im plicit Newm ark Constant
Average Acceleration (Newm ark $=0.25) m ethod [Clough 1993]. The tim e step should be less than 0.1 of the
period of the highest m ode of free vibration that contributes significantly to the response of the structure. In
general for m ulti-storey fram ed buildings, experience has shown that 0.01 seconds is satisfactory but for m ost
digitized earthquake accelerogram s the tim e step should never exceed 0.02 seconds. However, the user m ust
investigate the accuracy of the analyses by checking that using a sm aller tim e-step the results do not change
significantly. The Newm ark schem e has been m odified from the original increm ental equilibrium m ethod to an
equilibrium approach to ensure the m aintenance of equilibrium at each tim e-step. As a further option, the
Newton-Raphson iteration schem e can be em ployed to converge to a true solution at each tim e-step. Any
residual force error is carried forward to the next tim e-step in a self-correcting procedure. The Constant Average
Acceleration m ethod has the advantage of being unconditionally stable but also the advantage that not all
degrees of freedom need to have an associated m ass.

During the tim e step from tim e t to tim e t+)t the acceleration is assum ed to be constant

Integrating with respect to tim e over the tim e-step )t to get the velocity and displacem ent and rearranging to use
the increm ent in the displacem ent )u as the variable gives the increm ent in the acceleration

and the increm ent in the velocity as

Substituting into the equation of equilibrium at tim e t+)t gives

Noting that the stiffness term m ay be rewritten as

where [K(t)] represents the secant stiffness m atrix at tim e t and the elastic forces are the nodal equivalent of the
m em ber forces at tim e t and the m atrix [K T] is the current tangent stiffness m atrix.

Sim ilarly the dam ping term m ay be rewritten in term s of the nodal dam ping forces and the current tangent
dam ping m atrix and the increm ent of the velocities.

where the dam ping forces are those at tim e t and the matrix [C T] is the current tangent dam ping m atrix.

This m eans that the equation of equilibrium m ay be rewritten in the form

Substituting for the increm ents of acceleration and increm ents of velocity in term s of the increm ents of
displacem ent leads to the equation

If the dam ping m atrix is constant, i.e. does not change with tim e, this equation m ay be sim plified to give the

46
following equation

This equation m ay be solved for the increm ental displacem ents. The displacem ent, velocity and acceleration
vectors can now be updated and the m em ber forces at tim e t+)t com puted giving the elastic force vector and
the dam ping force vector at the new tim e-step can also be updated. After updating the dam ping and stiffness
m atrices the above sequence is repeated for the next tim e-step.

As m entioned above, this integration schem e is unconditionally stable but that does not im ply that it is
unconditionally accurate. The user has the responsibility to ensure that the tim e-step being used is sm all enough
to m aintain accuracy. Error will be caused by m odes that have too sm all a natural period of free vibration to be
accurately integrated with the chosen tim e-step and yet have a significant contribution to the response. Error will
also be caused in system s where there are very large changes to the stiffness of the structure within the tim e-step
and the change in the equilibrium is not well represented by the operation of the tangent stiffness on the
increm ent of displacem ents. These errors can be reduced by either decreasing the size of the tim e-step, by
using Newton-Raphson iteration within each tim e, or by a com bination of these approaches. The user therefore
should, for new types of structure or new problem s outside their experience, check the answers by repeating the
analysis using a sm aller tim e-step. If there are noticeable differences in the response then this indicates that the
tim e-step is not sm all enough and further investigation to find a tim e-step that is sm all enough to m aintain
accuracy needs to be m ade.

In any circum stance, do not use a tim e-step that is greater than the tim e-step at which the excitation, i.e. the
earthquake accelerogram , is digitized. If this is not followed then the input excitation used in the analysis will not
represent the real excitation.

47
9.2 Explicit Central Difference M ethod

An alternative m ethod is the use of an explicit Central Difference m ethod. This m ethod is only conditionally stable
in that the tim e step m ust be less than 0.5 of the shortest natural period of the structure. For m ost fram ed
structures this m ethod is not very econom ic for earthquake type loadings and is not generally recom m ended.
Most fram ed structures have very sm all wave travel tim es between nodes, particularly along the axially stiff girder
m em bers. This im plies very short natural periods for these m odes. Only a lum ped or diagonal m ass m atrix is
perm itted with this integration schem e. All degrees of freedom m ust have m ass for this schem e to work.

The equation of equilibrium is

and noting that [K]{u} is the nodal force vector associated with the current m em ber forces and that the second
term on the left hand side of the equation is the nodal dam ping force vector, rearranging and m ultiplying through
by the inverse of the m ass m atrix leads to

Using C entral Differences for the accelerations in term s of the displacem ents at tim e t+)t and t-)t gives the
increm ent of displacem ent

therefore

From the expression for the velocity at tim e t+)t

and at tim e t

and therefore the increm ent of velocity is given by

Knowing the increm ents of displacem ent and velocity the displacem ents and velocities can be updated to the next
tim e step. The m em ber forces can now be evaluated and transform ed into the nodal force vector and the nodal
dam ping force vector can also be com puted. The new applied force vector can be evaluated and the new
accelerations can be com puted and the sequence of operations in the step above is repeated.

48
10 SMALL and LARGE DISPLACEMENTS
Sm all displacem ent analyses are appropriate for m ost dynam ic analyses. In this case the m em bers stiffnesses
are not affected by the deform ations of the structure and the nodal coordinates rem ain unchanged during the
analysis. RUAUMOKO can m odel structures where the displacem ents are sufficient to require a large
displacem ent analysis or where the axial forces in m em bers affect their stiffnesses.

In large displacem ent analyses the coordinates are updated at every tim e-step and the stiffnesses, allowing for
changes in the axial forces in the beam or wall m em bers and the changes in geom etry in the m em bers, are re-
com puted at every tim e-step. This procedure is com putationally expensive. but is im portant if the fram e is
undergoing large displacem ents. An exam ple would be when the interstorey drifts are significantly greater that
1% of the storey height or where the axial forces in Fram e m em bers are large.

The P-Delta option, where the displacem ents are assum ed to be sm all and the coordinates are unchanged but
the beam and colum n m em ber stiffnesses are adjusted for the axial forces from the static analysis. This allows
for the lateral softening of the colum ns due to the gravity loads. The P-Delta effect is assum ed to be constant as
the increase in stiffness on one side of the structure due to overturning m om ents is offset by the decrease in
stiffness on the other side of the structure. This approach has a m inim al effect on the cost of the analysis. This
option is only really applicable to fram es with vertical colum ns and where the total vertical force on the colum ns
of a floor is constant, i.e. where the applied dynam ic actions are only horizontal. In other cases the Large-
Displacem ent option is m ore appropriate.

The effect of the axial force on fram e and wall m ember stiffness is shown in Figure 47. There are two
com ponents, the first is the softening of the flexural stiffness of the m em ber and the second is the 'string' stiffness
reduction of the lateral stiffness of the m em ber. The nett effect is the sam e as subtracting the geom etric stiffness
from the m em ber stiffness but is com putationally m ore efficient. The first part also accounts for the effects of
the axial forces on the m em ber m om ent-rotation properties.

Figure 52 Geometric Stiffness Effects

49
11 RELATIVE or TOTAL DISPLACEMENTS
The program is written so that the displacem ents, velocities and accelerations are those m easured relative to
the fixed foundation or base of the structure. If a travelling w ave input is im plied by setting the appropriate flags
on the nodal point data then the program will work in a total displacem ent, velocity and acceleration system . This
m ay be achieved, in general, for a rigid based structure by the expedient of slaving all the base nodes to the one
input node or by using very large wave velocities.

The equation of m otion for a m ulti-degree of freedom structure subjected to a tim e varying load m ay be written
as:

where [M], [C] and [K] are the m ass, dam ping and stiffness m atrices, {v( }, {v0 } and {v} are the accelerations,
velocities and displacem ents of the structure and { P(t)} is the tim e varying loading on the structure.

For the case of an earthquake, the only forces considered to be acting on the structure will be the static dead and
live loads, i.e. {P(t)} is a constant force. The dynam ic effects in the structure are caused by the m otion of the
ground supporting the structure.

In the above equation, the displacem ents are the total displacem ents of the structure m easured from som e fixed
reference point. The usual m easure of displacem ents in structural analyses, those relative to the ground is not
im m ediately applicable because the ground itself is m oving. However, m ost engineering calculations use relative
displacem ents {u}, i.e. displacem ents of the structure with respect to its foundation, and the total displacem ents
can be represented by a com bination of this relative displacem ent and the ground displacem ent. This is
applicable where the whole foundation of the structure m ay be considered as having the sam e im posed ground
m otion.

Figure 53. Total and Relative Displacement

If {u} is the displacem ent of the structure relative to the rigid foundation then

where {r} is the displacem ent of the structure due to a unit ground displacem ent and u g(t) is the ground
displacem ent history.

50
 Figure 54. Only the x Degrees of Freedom are Affected

Figure 55. {r} are the Influence Coefficients due to a Unit Support Displacement

Figure 56. {r} are the Influence Coefficients due to a Unit Support Displacement

51
For m ultiple support situations

where each colum n of [r] is the displacem ent of each degree-of-freedom due to a unit displacem ent of each
foundation degree-of-freedom in turn.

There will also be m ultiple {r} vectors if m ore than one directional com ponent of the earthquake excitation is
considered in the sam e analysis. The reader should note that real earthquakes have three orthogonal
displacem ent com ponents.

Substituting the second equation into the first gives

Given the ground acceleration u( g(t) this will have to be integrated with respect to tim e to give u0 g(t) and u g(t). If
the ground displacem ent history u g(t) is known it will have to be differentiated with respect to tim e to give the
velocity and acceleration histories of the ground.

For non-linear structures with m ultiple support input m otions the above equation is inconvenient as the vectors
{r} m ay also be functions of the displacem ent and in that case the first equation in total displacem ents will be
m uch m ore convenient to use. In this case the base displacem ents, velocities and accelerations are known and
as the loads {P} are constant the increm ental displacem ents of the structure can be found from a back-
substitution process in the increm ental equations of equilibrium .

If the ground m otion is considered to be uniform over the site, i.e. travelling wave effects are not considered and
the foundation is considered to undergo a rigid-body displacem ent, then the last equation m ay be considerably
sim plified.

For a rigid-body displacem ent no forces are generated within the structure. This is a necessary property of any
m em ber or structure stiffness m atrix.

If the usual assum ption that dam ping forces are considered to be only due to relative velocities is m ade then

and the equation of m otion becom es

W e m ay treat -[M]{r}u( g(t) as the effective earthquake force. Note the negative sign. The direction of the
earthquake in design calculations is not known and m any earthquake loadings code equations have dropped the
sign. However, for m ost analyses, particularly if the relative displacem ents are to be com bined with the ground
displacem ents, the sign is im portant. This is the equation of dynam ic equilibrium that is used in m ost dynam ic
analyses and is used in RUAUMOKO for relative displacem ent solutions.

If the structure is linearly elastic then the gravitational and earthquake loads m ay be treated separately and
com bined later using the Principle of Superposition. However, if there are any non-linearities in the m aterials,
or in the geom etry as the result of large displacem ents, then all the loading conditions have to be considered
together.

52
12 GENERAL PROCEDURES
12.1 Free-Format Input

All program data (except the earthquake acceleration records which are in a standard accelerogram form at) is
read under a free-form at control i.e. no special form at for the input line is required. For help on the use of the
com m and processor type $HELP at any prom pt. The field definition or delim iter is one or m ore blank colum ns,
an equals sign (=) or a com m a (,). In general, the integer I or floating point F num bers m ust be provided on the
line in the prescribed sequence and trailing fields, if left blank, are interpreted as zero. The floating point num bers
m ay be in the usual form i.e. 267.3 etc. or an exponential form e.g. 2.673E 2, in both cases the decim al point is
optional and in the exponential case there m ust be no blank space between the m antissa 2.673 and the letter
E (or e). The exponent m ust not have a decim al point. Integer num bers m ust not have a decim al point. All
num bers m ay have plus + or m inus - signs or be unsigned. Num bers m ay also be input in the form of arithm etic
expressions, i.e. ((2^3+5)/10) which is equivalent to 1.3 but which m ay indicate how it was derived, please check
$HELP for m ore details on the use of these expressions. An input line is term inated after reaching colum n 80
or on encountering an isolated exclam ation m ark ! i.e. the exclam ation m ark m ust be preceded by and followed
by at least one blank colum n. Any characters following the exclam ation m ark are ignored. Alphanum eric fields
or characters are autom atically converted to upper case unless they are protected by single or double quotation
m arks ( ' or " ). Please see the reference m anual for the TinyClip com m and processor used by all prgram s in
the Ruaum oko suite.

A line beginning with an asterisk * in colum n 1 is treated as a com m ent line, is printed in the output file and is then
ignored. Blank lines are ignored in the input. Lines that are only for inform ation within the data file should have
an exclam ation m ark ! as their first non-blank character. Any com m ents beyond the exclam ation m ark are
ignored by the reader.

The only valid characters, except for alphanum eric fields where any ASCII character is acceptable, are the digits
0-9, the signs + and -, the decim al point . and under the above conditions the sym bols E, e, * and !.

In the description of the input data that follows in the latter part of this m anual the following convention is used.
Each input line is designated by a box as follows:

M AXIT M AXCIT FTEST W AVEX WAVEY

where the variables M AXIT etc. are described in the lines below the box indicating the num erical values required
by the program and the type INTEGER, REAL or CHARACTER is shown by an I, F or A at the end of the
description line.

12.2 Units

Any consistent set of units m ay be used. However, care m ust be exercised to ensure that ALL quantities are in
the sam e units. Note: in the program weights are input and internally converted to m asses and that the ground
accelerations are in units of the acceleration of gravity.

12.3 Numbering

All sequences are num bered in sequences starting at 1. This applies to nodes, m em bers, section properties,
m asses and loads. All data item s m ust be supplied in ascending order. Traditionally nodes, or nodal points, are
num bered in such a way that the nodal-point difference for any m em ber is m inim ized reducing the band-width
of the stiffness m atrix and the com putational cost of the analysis. This is not im portant as the program has an
autom atic m esh renum bering schem e which optim ises the equation num bering. The user does not see this
renum bering as an internal look-up table relates the nodal displacem ents to the equation or degree-of-freedom
num bers. The difference in the original stiffness m atrix storage requirem ent and the optim ised size are output
in the statistics at the end of the analysis.

53
13 RESULTS
13.1 Initial Input Echo

All input data is printed in the output file.

13.2 Static Analysis

W hen any static load is placed on the structure (dead and static live load) then the displacem ents (translations
and rotations) of all nodes are printed as well as the internal actions (forces and m om ents) in all m em bers of the
structure.

13.3 M odal Analysis

If a m odal analysis is required then for each m ode of free vibration the natural frequency, period and the
equivalent viscous dam ping im plied by the chosen dam ping m odel will be printed. The m ode shapes will be
printed if requested. Then for earthquake analyses the Participation Factors and the Modal Masses are
com puted for all output m odes. The is also a running sum of the contribution of the Modal Masses to the Total
Mass acting in the earthquake excitation direction

13.4 Dynamic Time-History

Details of selected node displacem ents as well as selected m em ber axial forces, end m om ents and shears m ay
be printed at any selected tim e-step interval throughout the analysis starting at the end of the first step.

In a sim ilar m anner, data m ay be output to a post-processing file for use in the post-processing program
DYNAPLOT.

At the end of the tim e-history a sum m ary (envelopes) of the results together with m axim um plastic displacem ents,
m em ber ductilities and, if required, dam age indices are printed. The output ends with som e statistical inform ation
on the analysis.

If the analysis term inates abnorm ally, check the output file for error m essages. These are all included near the
end of the output file.

54
14 SIGN CONVENTIONS
14.1 Nodes - Displacements and Forces

A right-handed Cartesian coordinate system is used and the positive displacem ents and forces are shown below.
Right-hand screw rule im plied for m om ents.

Figure 57. Nodal Point Displacement and Rotation Sign Convention.

14.2 Frame and Foundation M embers Displacements and Forces

Axial elongations and hence tensile forces are positive. Applied m om ents, together with fixed end and yield
m om ents, are positive as shown below. A positive rotation of the equivalent plastic hinge is the result of a
positively applied m om ent. The sense of the positive forces and m om ents are shown below. A positive curvature
is associated with a positive bending m om ent.

Figure 58. Beam Forces and M oments Sign Convention.

55
14.3 Spring, Damper, Tendon and Contact M embers

Longitudinal or x forces and deform ations are positive when tensile. The Transverse or y forces and
deform ations are positive when the shear at end 2 of the m em ber is in the positive y direction and the
corresponding action at end 1 is in the -y direction. Mom ent and rotation is positive in the sam e sense as in the
beam m em bers above noting that in these m em bers M 1 = M 2.

Figure 59. Spring, Damper, Contact and Tendon Force and M oment Sign Convention.

56
14.4 Quadrilateral Finite Element

Tensile stresses are positive and the positive shear stresses and the resultant forces and m om ents are indicated
in Figure 60.

In-Plane Forces/unit length

Bending M oments/unit length

Figure 60. Quadrilateral Actions Sign Convention.

14.5 M asonry Panel Elem ents

The strut forces are tension positive and the shear is positive when the x displacem ent increases as y increases.
Plate Bending Mom ents as for Quadrilateral Finite Elem ents.

57
15 GRAPHICS
15.1 On-Screen Graphics

If the program is being run in an interactive m ode, such as on a personal com puter or workstation then it is
possible to have the deform ed shapes and plastic hinge pictures produced on the output screen. In general,
colour graphics is used if it is available though the user has the otion of selecting m onochrom e graphics. For the
spring m em bers the m em ber is drawn in three segm ents and the colour shown is that for each of the three
actions, the displacem ent springs dom inating the colour choice unless only rotational springs are in use then the
rotational springs control the colour. The pictures are produced every tim e the plastic hinge distribution changes
if the variable KPLOT is zero or every KPLOT tim e steps if the variable KPLOT is greater than zero.

The use of this option slows the program down by approxim ately 30 per cent. For this reason it is recom m ended
that the value of the variable KPLOT be such that the pictures are produced at, say, every tenth of a second
through the analysis.

The m em bers, when elastic, are shown in green. Rigid links and rigid end-blocks are shown in black.

In Fram e elem ents plastic hinges form ing with positive m om ents are shown in red and negative m om ents are
shown in blue. If the hysteresis rule has a slack region the hinge region is shown as yellow. If the Izz is greater
than Iyy then the z axis behaviour governs the colour choice but if Iyy is greater than Izz then the y axis behaviour
governs. Axial yield is shown by colour, red tension, blue com pression, in the central region of the m em ber.

Spring m em bers show x, y and z yield in the first, second and third segm ents of the length of the m em ber. The
force com ponents govern unless the displacem ent springs are of zero stiffness when the m om ent com ponents
govern the colour choices. If the m em ber is of zero length then it is invisible. The colour choice is green, red,
blue or yellow depending on whether the m em ber is elastic, yielding with a positive action, yielding with a negative
action or in a slack region of the hysteresis loop.

Dashpot and tendon m em bers are invisible during the tim e-history analysis and contact elem ents are visible only
when contact is m ade showing red in tension or blue in com pression.

Masonry panel elem ents are shown in yellow with the struts showing their yield status with the appropriate colours
for the equivalent spring m em bers. The m asonry panel elem ents, for plotting, are shrunk by 10% around their
centre of gravity to separate from the surrounding elem ents

The quadrilateral elem ents, for plotting, are shrunk by 10% around their centre of gravity to separate them from
the surrounding elem ents, and as they are elastic, they are green in colour.

58
16 DUCTILITIES
At the end of the analysis the ductilities are com puted for any beam or spring m em ber that has exceeded its yield
strength during the analysis. The ductility is defined as the m axim um deform ation divided by the yield
deform ation. For fram e m em bers the ductility is a curvature ductility. For colum n m em bers, if the yield
deform ation is that associated with the m axim um yield m om ent then this m eans that the ductilities calculated are
the m inim um possible m em ber ductilities. .

16.1 Giberson Beams and M em ber Ductility

Figure 61 Giberson Hinge M odel

Assum ing that the m om ent is constant in the hinge region. In hinge region equivalent radius of curvature is D (i.e.
curvature is 1/D) and this is equilibrated with the action of two lengths of m em ber with curvature 1/r and the plastic
hinge with rotation ,.

From geom etric considerations

From Mom ent Curvature

59
 where the flexibility of Giberson spring and p = the bi-linear factor

Note:

Multiplying by D, and dividing by EI

As the plastic hinge spring and the elastic beam are in series one has to add the flexibilities and invert to get the
stiffness of the m em ber.

For exam ple: assum e plastic hinge at end 1 only.

Figure 62. Giberson Beam with Hinge at End 1

60
Inverting to get stiffness m atrix
This can be transform ed to a beam with transverse displacem ent and rotation at each end by pre and post

m ultiplying [s] by ["] where

Figure 63. Beam W ith Degrees of Freedom

where L = m em ber length.

This gives the m em ber stiffness m atrix

61
If the spring flexibility is zero ie " = 0 this reduces to the norm al stiffness m atrix.

BEAM DUCTILITY exam ple for a Giberson Cantilever Beam

Bi-linear factor p.
Plastic hinge length H.

Figure 64. Cantilever Beam

Mem ber Stiffness

62
Static condensation to rem ove 2 degree of freedom

as expected

Curvature

At yield

Inelastic Case

From static condensation

where

Let beam have a ductility of :

63
Plastic curvature

where pEI = current stiffness in the hinge zone.

The curvature ductility is therefore

If and

then

If a hinge form s at both ends of a beam in a fram e the new m em ber stiffness will be required with hinge flexibility
at both ends of the m em ber.

16.2 Beam-Column M embers

The ductility calculation requires a value at the yield curvature in order to com pute the curvature ductility. The
axial force in colum n m em bers varies during the dynam ic analysis in plying available curvature calculation at any
stage. In RUAUMOKO the default yield curvature used to com pute m em ber ductilities is that associated with the
axial load in the colum n under the static load.

64
17 DAMAGE INDICES
If dam age indices are to be com puted for the beam or spring m em bers the input requires the ultim ate ductilities
for the m em ber actions. It is im plied that these are the ductilities at which the m em ber is assum ed to fail. This
has no effect during the tim e-history analysis but they are only used to com pute the dam age indices at the end
of the analysis. The num ber of cycles of inelastic behaviour is actually the num ber of tim es that m em ber action
unloads from the inelastic part of the hysteresis spine curve divided by 2. A Dam age Index of 1.0, assum ing
proper ultim ate ductilities are specified, im plies failure and a value of 0.4 is about the lim it of repairable dam age.
[Carr 1993]

Letting : m, : y, : j, : u, F m, F y, * y,E h, E u and E m be the m axim um , yield, cycle j and ultim ate ductilities, the m axim um
and yield actions, the yield displacem ent (curvature) and the dissipated hysteretic energy and the work done at
ultim ate and m axim um ductilities respectively the seven dam age indices com puted are:

1. Deform ation

2. Park and Ang [Park 1985]

3. Bracci et al [Bracci 1989]

4: Roufaiel and Meyer [Roufaiel 1987]

5: Cosenza, Manfredi and Ram asco (Ductility) [Cosenza 1993]

6. Banon and Veneziano [Banon 1982]

7. Krawinkler and Zohrei [Krawinkler 1983]

65
18 ENERGY
The program com putes kinetic, viscous and elastic energies as well as the applied work done during the analysis
and they are written to the post-processor .RES file. These results are only available from the post-processor
program DYNAPLOT.

The equation of increm ental equilibrium is:

where M, C T and K T are the Mass, Tangent Dam ping and Tangent Stiffness m atrices, *P is the increm ental load
and *u is the increm ental displacem ent and the dots denote differentiation with respect to tim e to give the
increm ental velocities and the accelerations. In an earthquake analysis using a relative displacem ent form ulation
the increm ental loads are functions of the earthquake accelerogram . However, in a total displacem ent
form ulation the right hand side of the equation has only the static loads.

At every step in the analysis equilibrium m ust be m aintained so that equilibrium is m aintained

W here [C S] and [K S] are the secant dam ping and stiffness m atrices. i.e.

where F Inertia, F Damping, and F Elastic are the inertia, dam ping and elastic forces at the nodal degrees of freedom and
P(t) are the applied nodal forces. Multiplying both sides of this equation by the transpose of the nodal velocity
vector and integrating with respect to tim e yields

The first term is the relative kinetic energy for relative displacem ent analyses and the actual kinetic energy if a
total displacem ent analysis is being carried out. The second term is the dissipated energy due to viscous
dam ping. The third term is the sum of the strain energy stored in the structure and hysteretic or plastic work
dissipated in the structure as the energy is a function of the forces in the inelastic structure and the displacem ents
of the structure. Not all of the elastic strain energy is recoverable if the structure has undergone inelastic
deform ation because there will m ost likely be self-equilibrating locked in forces in the structure at the end of the
analysis. To get a m easure of the final state of the structure one should allow the structure to respond in free
vibration for several cycles after the earthquake excitation has been com pleted. This is, however, seldom
perform ed. The program also com putes separately the plastic work done during the analysis but because this
is currently com puted outside the hysteresis routines it is not as accurate as the other energy term s.

It m ust be noted that the above equation of energy equality is not satisfied in the static analysis since the applied
work done is the product of the loads and the displacem ents and the internal strain energy is one half of the
product of the elastic forces and the displacem ents. This is a requirem ent of the Theorem of Minim um Potential
Energy. This shows as a slight offset between the sum of the term s on the left hand side of the energy equation
and the applied work done. The work is not equated in the static analysis but the Total Potential energy is a
m inim um in the static analysis. If, however, the difference grows during the analysis it indicates a loss of
accuracy in equilibrium and, consequently, a sm aller tim e-step should be used and/or iteration on residuals m ay
be required.

66
19 REFERENCES
Baber, T.T. and W en, Y. Random Vibration of Hysteretic Degrading Systems. J. Eng. Mech. Div., ASCE,
V107, No. EM6, Dec.1981, pp 10691087.

Banon, H. and Veneziano, D. Seismic Safety of Reinforced Concrete Members and Structures. Earthquake
Engineering and Structural Dynam ics, Vol. 10, 1982, pp179193.

Bessasson, B. Assessment of Earthquake Loading and Response of Seismically Isolated Bridges. Division of
Marine Structures, The Norwegian Institute of Technology, University of Trondheim , Norway, 1992.

Bracci, J.M., Reinhorn, A.M., Mander, J.B. and Kunnath, S.K. Deterministic Model for Seismic Damage
Evaluation of Reinforced Concrete Structures. Technical Report NCEER-890033, National Center
for Earthquake Engineering Research, State University of New York at Buffalo, 1989.

Calvi, G.M., Magenes, G. and Pam panin, S. Relevance of beam-Column Joint Damage and Collapse in RC
Frame Assessment. J.Earthquake Engineering, Vol 6. Special issue 1, 2002, pp 75-100.

Carr, Athol J. Damping Models for Inelastic Structures, Proc. Asia Pacific Vibration Conf. 97, Kyongju, Korea,
Nov. 913, 1997, Vol. 1, pp 4248.

Carr, Athol J. Damping Models for Time-history Structural Analyses, Proc. Asia Pacific Vibration Conf.-05.
Langkawi, Malaysia, Nov 27-27, 2005, pp287-293.

Carr, A.J. and Tabuchi, M. The Structural Ductility and the Damage Index for Reinforced Concrete Structure
under Seismic Excitation. Proc. Second European Conf. on Struct. Dynam ics, EURODYN'93,
Trondheim , Norway, 2123 June 1993, Moan, T. et al, Eds. Balkem a, 1993, pp 169176.

Carr, Athol J. Dynamic Analysis of Structures. Bull. NZ Nat. Soc. Earthquake Eng. Vol. 27. No. 2, June 1994,
pp 129146.

Carr, A.J., Moss, P.J. and Filiatrault, A. Pounding of Adjacent Structures During Earthquakes: A Review of
the State of Current Knowledge. Proc. 7 th Canadian Conference on Earthquake Engineering,
Montreal, 1995, pp 221228.

Carr, A.J. A Refined Finite Element Analysis of Thin Shells Including Dynamic Loadings, Ph.D. Thesis,
University of California, Berkeley, 1967, 224p.

Caughey, T.K. Classical Normal Modes in Damped Linear Systems. J. Appl. Mech., Vol 27, 1960,
pp 269271.

Cham bers, J.D. A Distributed Spring Soil Model for Dynamic Soil-Structure Interaction Analysis, M.E. Thesis,
Departm ent of Civil Engineering, University of Canterbury, February 1998.

Clough, Ray W . et al., ADAP A Computer Program for Static and Dynamic Analysis of Arch Dams.
University of California, Berkeley, California, 1973.

Clough, R.W . and Penzien, J. Dynamics of Structures. Second Edition. McGraw-Hill, New York, 1993, 738p.

Consenza, E., Manfredi, G. and Ram asco, R. The Use of Damage Functionals in Earthquake Engineering: A
Comparison Between Different Methods. Earthquake Engineering and Structural Dynam ics, Vol. 22,
1993, pp 855868.

Constantinou, M.C. and Tadjbakhsh, I.G. Hysteretic Dampers in Base Isolation: Random Approach. J. Struct.
Eng. ASCE, Vol. 111, No. 4, Apr. 1985, pp 705721.

Cook, R.D. Remarks About Diagonal Mass Matrices. Int. J. Num erical Methods in Engineering, Vol. 17, 1981,
pp 14271449.

Crisafulli, F.J. Seismic Behaviour of Reinforced Concrete Structures with Masonry Infills. Ph.D. Thesis,
Departm ent of Civil Engineering, University of Canterbury, July 1997.

67
Crisp, D.J. Damping Models for Inelastic Structures. M.E. Report, Departm ent of Civil Engineering, University
of Canterbury, February 1980.

Davis, R.O. Pounding of Buildings Modelled by an Impact Oscillator. Earthquake Engineering and Structural
Dynam ics, Vol. 21, 1992, pp 253274.

Dodd, L. The Dynamic Behaviour of Reinforced-Concrete Bridge Piers Subjected to New Zealand Seismicity.
Ph.D. Thesis, Departm ent of Civil Engineering, University of Canterbury, February 1992, 460p +
appendices.

Dodd, L.L. and Restrepo-Posada, J.I. Model for Predicting Cyclic Behaviour of Reinforcing Steel. J. Structural
Engineering, ASCE, Vol. 121, No. 3, Mar. 1995, pp 433445.

Duncan, J.M. and Chang, C.Y. Nonlinear Analysis of Stress and Strain in Soils. Proc. ASCE, SM5, Vol. 96,
pp 16291653, 1970.

Em ori, K. and Schnobrich, W .C. Analysis of Reinforced Concrete Frame-W all Structures for Strong Motion
Earthquakes. Civil Engineering Studies. Structural Research Series No.434, University of Illinois,
Urbana. Illinois, Dec. 1978.

Faifar, P. and Krawinkler, H. Eds. Nonlinear Seismic Analysis and Design of Reinforced Concrete Buildings.
Elsevier Applied Science, London, 1992, 305p.

Fukada, Y. Study on the Restoring Force Characteristics of Reinforce Concrete Buildings. (In Japanese).
Proc. Kanto District Sym posium , Architectural Institute of Japan, Tokyo, Japan, No. 40, 1969.

Hill, K.E. Dynamic Properties of Ring Springs for Use as Seismic Energy Dissipators. Proc. NZSEE Technical
Conference, W airakei, 1820 March 1994, pp 96101.

Holand, Ivar and Aldstedt, Erik, Arch Dam analysis by Finite Element Analysis, Institute for Statikk, NTH,
Trondheim , Norway, January 1968.

Hunt, S.J., Semi-Active Smart Dampers and Resettable Actuators for Multi-level Seismic Hazard Mitigation of
Steel Moment Resisting Frames. M.E. thesis, Departm ent of Mechanical Engineering, University of
Canterbury, Christvhurch,New Zealand, 2002 in preparation.

Ishihara, Kenji. Soil Behaviour in Earthquake Geotechnics. Clarendon Press, Oxford, 1996.

Jury, R.D. Seismic Load Demands on Columns of Reinforced Concrete Multi-storey Frames. M.E. Report
78-12, Departm ent of Civil Engineering, University of Canterbury, February 1978.

Kabeyasawa, T., Shiohara, H., Otani, S. and Aoyam a, H., Analysis of the Full-scale Seven-storey Reinforced
Concrete Test Structure. Journal of the Faculty of Engineering, University of Tokyo, (B), Volum e
XXXVII, No. 2, 1983, pp 431478.

Kaldjian, M.J. Moment-Curvature of Beams as Ramberg-Osgood Functions. J. Struct. Div. ASCE, Vol. 93,
No.ST5, Oct. 1967, pp 5365.

Kanaan, A.E. and Powell, G.H. General Purpose Computer Program for Inelastic Dynamic Response of
Plane Structures. Report EERC 73-6, College of Engineering, University of California, Berkeley, April
1973.

Kato, D., Otani, S., Katsum ata, H. and Aoyam a, H. Effect of W all Base Rotation Behaviour of Reinforced
Concrete Buildings. Proc. 3rd South Pacific Conf. on Earthquake Engineering, W ellington, NZ., May
1983.

Kent, D.C. and Park, R. Flexural Members with Confined Concrete. Journal of the Structural Division, ASCE.
Vol. 97, No. ST7, July 1971, pp 19691990.

68
Keshavarzian, M. and Schnobrich, W .C. Computed Nonlinear Seismic Response of R/C W all-frame
Structures. Report UILU-ENG-84-2004, Dept. of Civil Engineering, University of Illinois, Urbana,
Illinois, May 1984.

Kivell, B.T. Moss, P.J. and Carr, A.J. Hysteretic Modelling of Moment-Resisting Nailed Timber Joints. Bull.
N.Z. Nat. Soc. Earthquake Engineering, Vol. 14, No. 4., Dec. 1981, pp 233243.

Kondor, R.L. and Zelasko, J.S. A Hyperbolic Stress-Strain Formulation of Sands. Proc. 2nd Pan Am erican
Conf. on Soil Mechanics and Foundation Engineering, 1963, pp 289324.

Krawinkler, H. and Zohrei, M. Cumulative Damage in Steel Structure Subjected to Earthquake Ground
Motions. Com puters and Structures, Vol. 16, No. 14, 1983, pp 531541.

Li Xinrong. Reinforced Concrete Columns Subjected to seismic Loading. Ph.D Thesis, Departm ent of Civil
Engineering, University of Canterbury, 1994.

Liu, Aizhen, Seismic Assessment and Retrofit of Pre-1970s Reinforced Concrete Frame Structures. Ph.D.
Thesis, Departm ent of Civil Engineering, University of Canterbury, 2001. 398p.

Matsushim a, Y. Discussion of Restoring Force Characteristics of Buildings, the Damage from Tokachi-oki
Earthquake, (in Japanese). Report, Annual Meeting, Architectural Institute of Japan, August 1969,
pp 587588.

Moss, P.J. and Carr, A.J. The Effects of Large Displacements on the Earthquake Response of Tall Concrete
Frame Structures. Bull. N.Z. Nat. Soc. Earthquake Engineering. Vol. 13, No. 4, Decem ber 1980.

Muto, K., Ohm ori, N., Sugano, T., Miyashita, T. and Shim izu, H. Non-linear Analysis of Reinforced Concrete
Buildings. Theory and Practice in Finite Elem ent Structural Analysis, Yam ada, Y. and Gallagher, R.H.
Eds. University of Tokyo Press, Tokyo, 1973, pp 399421.

Otani, S. SAKE, A Computer Program for Inelastic Response of R/C Frames to Earthquakes. Report UILU-
Eng-74-2029, Civil Engineering Studies, Univ. of Illinois at Urbana-Cham paign, Nov. 1974.

Otani, S. Nonlinear Behaviour of Reinforced Concrete Building Structures Especially Under Earthquake
Motions. IASS Sym posium , Darm stadt, July 1978, Nonlinear Behaviour of Reinforced Spatial
Structures.

Otani, S. Non-linear Dynamic Analysis of Reinforced Concrete Building Structures. Canadian J. Civil
Engineering, Vol. 7, No. 2, 1980, pp 333344.

Otani, S. Hysteresis Models of Reinforced Concrete for Earthquake Response Analysis. J. Faculty of
Engineering, University of Tokyo, Tokyo, Vol. XXXVI, No. 2, 1981, pp 125159.

Otani, S. Kabeyasawa, T. Shiohara, H, and Aoyam a, H. Analysis of the Full-Scale Seven Storey Reinforced
Concrete Test Structure. Earthquake Effects on Reinforced Concrete Structures U.S.Japan
Research, Publication SP-84, ACI, 1985, pp 203239.

Park, R., Priestley, M.J.N. and Gill, W .D. Ductility of Square-Confined Concrete Columns. Proceedings
ASCE, Vol. 108, No. ST4, April 1982, pp 929950.

Park, Y-J. and Ang, A.H-S. Mechanistic Seismic Damage Model for Reinforced Concrete. J.Struct. Div.
ASCE, Vol. 111, No. 4, April 1985, pp 722757.

Pekcan, G., Mander, J.B. and Chen, S.S. The Seismic Response of a 1:3 Scale Model R.C. Structure with
Elastomeric Spring Dampers. Earthquake Spectra Vol. 11, No. 2, May 1995, pp 249267.

Priestley, M.J.N., Sritharan, S., Conley, J.R. and Pam panin, S. Preliminary Results and Conclusions from the
PRESS Five-Story Precast Concrete Test Building. PCI Journal, Vol. 44, No. 6, Nov/Dec 1999, pp.
4267.

69
Pyke, Robert, Nonlinear Soil Models for Irregular Cyclic Loadings. J.Geotechnical Eng.Div. ASCE, Vol. 105,
No. GT6, June1979,pp 715,726

Rahm an, A.M. Seismic Pounding of Adjacent Multiple-Storey Buildings Considering Soil-Structure Interaction
and Through-Soil Coupling, Ph.D. Thesis, Departm ent of Civil Engineering, University of Canterbury,
1998.

Ram berg, W . and Osgood, W .R. Description of Stress-Strain Curves by Three Parameters. National Advisory
Com m ittee on Aeronautics, Technical Note 902, 1943.

Rem ennikov, A. and W alpole, W .R. Incremental Model for Predicting the Inelastic Hysteretic Behaviour of
Steel Bracing Members. Research Report 95-6, Departm ent of Civil Engineering, University of
Canterbury, Christchurch, New Zealand, October 1995, p 114.

Rem ennikov, A. and W alpole, W .R. Analytical Prediction of Seismic Behaviour for Concentrically-Braced
Steel Systems, Earthquake Engineering and Structural. Dynam ics, Vol. 26, 1997, pp 859874.

Rem ennikov, A.M. and W alpole, W .R. Modelling the Inelastic Cyclic Behaviour of a Bracing Member for
W ork-Hardening Material. Int. J. Solids & Structures, Vol. 34, No. 27, 1997, pp 349355.

Rodriguez, M.E., Restrepo,J.I. and Carr, A.J .Earthquake-induced Floor Horizontal Accelerations in Buildings.
Earthquake Engineering and Structural Dynam ics, Vol 31, 2002, pp 693-718.

Roufaiel, M.S.L. and Meyer C. Analytical Modeling of Hysteretic Behaviour of R/C Frames. J. Struct. Eng.
ASCE. Vol. 113, No. 3, March 1987, pp 429457.

Saiidi, M. and Sozen, M.A. Simple and Complex Models for Nonlinear Seismic Response of Reinforced
Concrete Structures. Report UILU-ENG-79-2031, Departm ent of Civil Engineering, University of
Illinois, Urbana, Illinois, August 1979.

Satyarno, I. Pushover Analysis for the Seismic Assessment of Reinforced Concrete Buildings, Ph.D. Thesis,
Departm ent of Civil Engineering, University of Canterbury, March 1999.

Satyarno, I., Carr, A.J. and Restrepo, J. Refined Pushover Analysis for the Assessment of Older Reinforced
Concrete Buildings, Proc. NZ Nat. Soc. for Earthquake Engg, Tech. Conf. W airakei, 2729 Mar,
1998, pp 7582.

Selvadurai, A.P.S. Elastic Analysis of Soil-Foundation Interaction. Developm ents in Geotechnical

Engineering, Vol. 17, Elsevier Scientific Publishing Com pany, The Netherlands, 1979.

Sharpe, R.D. The Seismic Response of Inelastic Structures. Ph.D Thesis, Departm ent of Civil Engineering,
University of Canterbury, Novem ber 1974.

Stewart, W .G. The Seismic Design of Plywood Sheathed Shear W alls. Ph.D Thesis, Departm ent of Civil
Engineering, University of Canterbury, March 1987, 395p.

Taylor, R.G. The Nonlinear Seismic Response of Tall Shear W all Structures. Ph.D. Thesis, Departm ent of
Civil Engineering, University of Canterbury, Novem ber 1977.

Um em ura, H. and Takizawa, H. Dynamic Response of Reinforced Concrete Buildings. Structural Engineering
Docum ents, IABSE, Zurich, 1982, 64p.

W en, Y. Method for Random Vibration of Hysteretic Systems. J. Eng. Mech. Div., ASCE, Vol. 102, No. EM2,
April 1976, pp 249263.

W idodo. The Rocking of Multi-storey Buildings. Ph.D Thesis, Departm ent of Civil Engineering, University of
Canterbury, February 1995, 400p.

W ilson. E. L. and Dovey. H. H. Solution or Reduction of Equilibrium Equations for Large Complex Structural
Systems. Advances in Engineering Software, Vol. 1, No. 1, 1978, pp 1925.

70
W ilson, E.L. and Penzien, J. Evaluation of Orthogonal Damping Matrices, Int. J. Num erical Methods in Engg.,
Vol. 4, 1972, pp 510,

W olf, John P. Foundation Vibration Analysis Using Simple Physical Models. Prentice Hall, Englewood Cliffs,
NJ, 1994.

Zhu, K., Al-Berm ani, F.G.A., Kitipornchi, S. and Li. B. Dynamic Response of Flexibly Jointed Frames.
Engineering Structures, Vol. 17, No. 8, 1995, pp 575580.

20 REFERENCES with examples of the use of Ruaumoko.

Christopoulos, C, Filiatrault, A, Uang, C-M and Folz, B. Post-tensioned Energy Dissipating Connections for
Moment Resisting Steel Frames. J. Structural Eng. ASCE, Vol 128, No. 9, Septem ber 2002,pp 1111-
1120.

Zhao, W .,Davidson, B.J. and Fenwich, R.C. The Influence of P-Delta Effects on Seismic Response of
Structures with Various Hysteretic Models. School of Engineering Report No. 606, Departm ent of
Civil and Resource Engineering, University of Auckland, Auckland, New Zealand. October 2001.
p213.

Christopoulos, C, Filiatrault, A, Principles of Passive Supplemental Damping and Seismic Isolation. IUSS
Press, Pavia, Italy, 2006, p479.

71
 RUAUMOKO-2D EXAMPLES

1 Earthquake Response

The file EXAM PLE.DAT is the data file describing a sm all 4 storey tim ber fram e. The fram e geom etry is
shown on page 3 together with a listing of the data file. The fram e has colum ns which are continuous over the
four storeys, they are assum ed to rem ain elastic and are pinned to the support at their bases. The four
girders are connected to the colum ns by steel nail plates which are assum ed to be elasto-plastic and yield at
a m om ent of plus or m inus 40 kN.m . Both m em ber self weight contributes to the m ass of the fram e as do
nodal point m asses representing the m ass of walls in the out of plane direction of the fram e and which act at
the nodal points. There are also initial m em ber fixed end forces and the other static loads acting at the nodes
which are required to get the correct initial conditions in the structure. In an inelastic analysis the static
displacem ents and forces cannot be added to the dynam ic response later as the principle of superposition is
no longer valid.

The fram e was subjected to 10 seconds of the North-South com ponent of the May 1940 El Centro
earthquake accelerogram . T his is contained in the file EL40NSC.EQB. This file is in the BERG form at where
each line contains 4 tim e-acceleration pairs of data and the total duration of the record is 20 seconds.

The file EXAM PLE.LIS, shown in the pages following the input data file, gives the output from the analysis
with the echo of the input data, the results of the static analysis, the m odal analysis and the enveloped results
of the tim e-history analysis as the fram e is subjected to the El Centro earthquake. The m em ber deform ations
and the ductilities are also shown and finally the dam age indices are com puted for the beam m em bers. The
final output section is the statistics from the analysis which shows how m uch array space etc. was used in the
analysis.

The pages following the output from the analysis also show som e of the print-screen pictures from the
analysis. The first is a picture of the m esh followed by the earthquake excitation history. The next two pictures
are two of the m ode shapes of the structure. These m ode shapes are not used in the analysis except for non-
Rayleigh dam ping m odels when they are used to construct a dam ping m atrix, but they provide the user with
som e confidence that the structure being analysed is correctly m odelled as the user should have a
reasonable idea of the natural periods that the structure should have as well as having a reasonable feel for
the actual shape of the m odes of free-vibration. The final picture is a snap-shot of the displacem ent at tim e =
2.0 seconds showing plastic hinges at both ends of the first floor beam and a plastic hinge at one end of the
second floor beam .

The final set of plots is from a DYNAPLOT analysis using the file EXAM PLE.RES which was produced by
RUAUMOKO during the tim e-history analysis. The file has stored the data for all nodes and for all m em bers
at an interval of 0.05 seconds (every 5 tim e-steps). The first plot is of the lateral displacem ents of nodes 9
and 3. The second plot is the bending m om ent at the left hand end of the first floor beam and the next plot is
the hysteresis plot showing the bending m om ent versus the curvature in the beam . Though the hysteresis is
m eant to be elasto-plastic som e of the corners appear to be rounded off but this is because DYNAPLOT has
no knowledge of the hysteresis rule, just the m om ent and curvature at each saved tim e-step, and it draws a
straight line from point to point. Even if results were saved every tim e step the curtailing of the corners will not
be com pletely elim inated. As a general rule, if you wish to plot hysteresis loops the results should be saved at
very sm all tim e-intervals. The consequence is very large .RES files. For norm al tim e history plotting
experience shows that every tenth of a second is usually adequate. The next plot is the % of the beam EI that
represents the Giberson plastic hinge spring at the end of the beam . If the value is 100% the beam -end is

1
elastic while if it is 0% the end of the m em ber is perfectly plastic. The final plot is the tim e-variation of the
energies of the structure. The first line shows the relative kinetic energy, the second line is the sum of the
relative kinetic energy and the dissipated energy due to dam ping, the third line shows the sum of the relative
kinetic energy, the energy dissipated by the dam ping and the elastic energy and the last line is the applied
input energy. There is always a sm all off-set due to the work done in the static analysis. Any further
deviations from the last two lines not being together would indicate that either too large a tim e step is being
used or iteration on residuals should be enabled so that equilibrium is better m aintained during the analysis.

To run these exam ples yourself take the following steps. All responses are com pleted by following them by
the RETURN or ENTER key.

1 Run the program RUAUMOKO-2D by giving the com m and RUAUM OKO2D followed by ENTER.
2 for the output listing file type EXAM PLE.LIS or any other file nam e that you wish i.e. JUNK. If the file
nam e already exists you will be asked if you wish to over-write it or try for a new nam e.
3 At the prom pt for the first excitation file type EL40NSC.EQB assum ing that it is in the current
directory. If not prefix the file nam e with the appropriate path.
4 At the request for the second excitation file, it is not actually required, just hit the ENTER key.
5 You are then asked for the nam e for the .RES file for post-processing in DYNAPLOT. The default
nam e is the sam e as the output listing file but with the extension .RES. If this is satisfactory just hit
the ENTER key otherwise respond with a suitable nam e. The extension .RES will be added
autom atically.
6 You are then asked if you want the on-screen graphics. Respond with y or yes.
7 The next prom pt asks if this is a data check run. To get the default NO just hit the ENTER key.
8 At the next prom pt which asks for the title for the analysis type $ADD EXAM PLE.DAT assum ing that
this file is in the current directory. If it is not in the current directory prefix the file nam e with the
appropriate path.
9 The next prom pt will ask if you want colour graphics.
10 W hen the m esh is plotted on the screen hit the ENTER key to allow the analysis to continue.
11 The next plot is that of the El Centro excitation. Hit the ENTER key to allow the analysis to continue.
12 The next m essage will ask which m ode you wish to see. If you wish to see none just hit the ENTER
key else type any num ber 1 to 4 followed by the num ber of cycles (optional) then ENTER to see that
m ode shape. After the num ber of cycles (default is five) and a quarter cycle the picture will freeze. To
return to the m ode shape selection his the ENTER key.
13 W hen the tim e-history com m ences the displays of the deform ed structure showing plastic hinge
locations starts. No action from the user is required. These pictures will continue until the 10 seconds
of the analysis has been com pleted.

2
3
4
5
6
7
8
9
10
1 If you wish to run the post-processor program DYNAPLOT type the com m and dynaplot. This
program has good built-in help files.

2 The first prom pt is for the output file. Just hit the ENTER key to get the default screen output.

3 The next prom pt is for the nam e of the post-processor file. The response is the sam e as the
response to point 6 in the RUAUMOKO input. Do not include the extension .RES in your file nam e. If
an ASCII file type was used DYNAPLOT will first search for an extension .RES then for an extension
.RAS.

4 The next prom pt is Do You W ant Colour. Again respond with ENTER if yes but with n or no if not, for
say, print/screen capture.

5 To produce the displacem ent plot for the fourth and first floors follow the following steps.

i Num ber of lines is 2.

ii Respond to the selection of graph type with t or tim e.
iii Select Node.
iv Select 1, the x-displacem ent.
v The Nodes are 9 3.
vi Tim e-step is the default 1.0.
vii The tim e range is the default 0 10 im plying from 0 tim es 1.0 to 10 tim es 1.0 seconds, i.e.
plotting from 0.0 to 10.0 seconds.
viii The y-axis interval is the default 0.0 which m eans that the program will autom atically select a
suitable interval based on the function to be plotted.
ix The num ber of y-axis grids, use the default -1 1. This im plies only one interval each side of
the tim e axis.
x Take the default paper size.
xi The title for the x-axis can be Time - (Seconds). If it is not enclosed in quotes then the tile
would be TIM E as the space would term inate the sequence and the text would be upper
cased autom atically.
xii The y-axis tile could be Displacement Nodes 9 and 3'.

6 The graph should now be plotted. In Microsoft W indows operating system s use the file pull-down
m enu and select the Save or Print options. On unix GKS graphics if hard copy has been enabled
select the Hard Copy option. W hen you have finished press the ENTER key to return to the m ain
m enu.

7 Another graph option m ay be selected or the default choice is to return to the operating system .

11
12
13
14
2 Pushover Analysis

The dynam ic loading option m ay be used to study the response of structures to gust loading, blast loading or
even cyclic loading. To do so the user m ust obtain or generate an equivalent loading history and m ust also
know the distribution of the loading on the structure.

Another use of this option is the pushover analysis. In this case a m onotonic increasing load is applied to the
structure until the ultim ate load is approached. In this case the load should be applied sufficiently slowly so
that the inertia effects do not generate an oscillatory response and the m axim um load should not exceed the
m axim um capacity of the structure as this m ay lead to failure of the analysis. In a pseudo dynam ic analysis
this is not quite so im portant as it will take tim e for the structure to collapse as the inertia will provide som e
constraint. The ram p function m ay be linear as in the exam ple shown or possibly of the form

where T L is the duration of the loading and which should be long when com pared with the fundam ental period
of the structure.

The loading distribution chosen in the exam ple in the file PUSHOVER.DAT is the seism ic loading distribution
for the equivalent static analysis of structures from the New Zealand Loadings Code NZS 4203:1992 which
distributes 92% of the base shear up the structure with the force at each level proportional to the weight at
that level tim es the height at that level divided by the sum of the weight tim es the height at each level
sum m ed over the whole structure. This is approxim ately a linear distribution from zero at the bottom to the
m axim um at the top. The rem aining 8% of the base shear is added to the top level forces to allow for higher
m ode effects. The results show that for a m axim um Base Shear of 30 kN plastic hinges have form ed at the
ends of the lower three girders and the displacem ents are starting to increase rapidly with increase in the load
showing that the structure is alm ost at its ultim ate load carrying capacity. The plot of the top floor
displacem ent shows only a very sm all oscillation m eaning that the inertial effects are sm all. The duration of
the ram p function is alm ost 11 tim es the fundam ental natural period of
the structure. The ram p function could possibly be applied m ore rapidly and a larger tim e-step could have
been used.

The sam e input has been used where the structure has no inertia, the results only showing a difference as
the end of the response is approached. The reduced apparent stiffness without the inertia effect shows that
the second hinge in the third girder appears a couple of tim e-steps (load-steps) earlier.

In this exam ple the excitation has been included in the input data file but if m any pushover analyses are to be
perform ed then such excitations could be placed in a library of earthquake accelerogram s. The ram p length
m ay be changed by varying the variable DELTAT in the data line 23b of the RUAUMOKO-2D m anual.

The plot of force versus displacem ent is obtained using the Base Shear plot option of DYNAPLOT where the
vertical axis is the Base Shear (the com bination of the shear at end 1 of m em bers 1 and 5) versus the top
floor displacem ent (x-displacem ent of node 9). The horizontal grid interval is 0.05 m with the grids from 0 to 5
giving a range of 0 to 0.25 m .

15
16
17
18
Department of Civil Engineering COMPUTER PROGRAM LIBRARY

Program nam e: Program type: Program code:

ASCII data History Output from RUAUM OKO ANSI Fortran77

Author: Date:
Athol J Carr April 29, 2007

ASCII post-processor files for DYNAPLOT.

(for program s com piled after 27th August 2001)

There is an option to use an ASCII post-processor file instead of the norm al BINARY post-processor file. The
ASCII file is readable in a text viewer while the BINARY file is not. There is a guide to the file structure for
those who have an interest in extracting data for their own post-processing program s. Though Ruaum oko
and the other program s are written in Fortran you m ay use any program m ing language to generate you own
post-processing program , i.e. Visual Basic, C, Java etc.

Ruaumoko-2D
If the control param eter IFM T on data line 2 of the Ruaumoko-2D input data (please see the user m anual) is
a 1, then instead of a BINARY file with the extension .RES being prepared for Dynaplot an ASCII text file
with the extension .RAS is generated.

Ruaumoko-3D
If the control param eter IFM T on data line 5 of the Ruaum oko-3D input data (please see the user m anual) is
a 1, then instead of a BINARY file with the extension .RES being prepared for Dynaplot an ASCII text file
with the extension .RAS is generated.

Use of post-processor program Dynaplot.

Operate Dynaplot as norm al, the progarm will first try to find a file with the extension .RES and if it is not
present then the program will search for a file with the extension .RAS. If the program finds the latter type file
the program knows that the post-processor file is an ASCII file. The first line of the post-processor file also
lets the program know whether the results are from Ruaumoko-2D or Ruaumoko-3D via the param eter
NSPACE, see later.

The ASCII post-processor file will be about twice the size of the equivalent BINARY file but m ay be useful for
users carrying out a large num ber of production param eter study analyses and who wish to to write a
program to extract som e particular result item s for comparisons between the analyses.

1
Programming language.

The program s are written in ANSI standard FORTRAN and output is under the control of the FORTRAN write
form ats. The file uses a m axim um line length of 128 characters and should be readable with W ordPad or
equivalent in Microsoft W indows operating system s. View .com or M ore m ay also be used to view these files.
You m ay have to scan the longer than 80 character lines, depending on the screen settings on your
com puter.

Each W RITE statem ent starts a new line and when the FORMAT is exhausted the output will be continued
on the next line as the FORMAT is repeated, i.e. if 12 item s are provided for in a line in the FORMAT and 38
item s are listed in the write com m and then the next 3 lines will have 12 num bers and the fourth line will have
the last 2 num bers of the set of 38 num bers.
Fortran Form ats.

The FORMAT n I m m eans n integers each taking m characters or spaces. In FORTRAN all data is
right-justified, i.e. all num bers are packed to the right of the field m. e.g. 6 I 5 m ea ns 6 integers having 5
colum ns each in a total of width of 30 colum ns, or character, across the line.

The FORMAT n F m.i m eans n floating point num bers each taking m characters or spaces with i digits after
the decim al point. If the num ber is too large for the field m then one gets a row of m asterisks, *, and if it is
too sm all, i.e. m ore than i zeroes after the decim al prior to any significant digits, one gets 0.0.

The FORM AT n E m .i m eans n floating point num bers each taking m characters or spaces with i digits after
the decim al point. The num ber is in scientific or exponent form , the first space is for the sign followed by a
zero, a decim al point and i significant digits. This is followed by the letter E, a + or - sign and 2 digits. The
sign and 2 digits is the power of 10 that the num ber ahead of the letter E m ust be m ultiplied by to get the
actual data item . W ith this form at then no m atter how large or sm all the num ber is always readable. If the
FORMAT is preceded by a 1P i.e. 1P12E10.3 m eans that the exponent has been reduced by one and that
the zero ahead of the decim al point has been replaced by a digit. This m eans that the num ber has not been
altered just that one m ore significant digit is available. The 1P holds for all rem aining E or F form ats in the
FORMAT statem ent, the I form ats are not affected. Note, in the E form at the m m ust be at least 7 greater
than the i.

The FORMAT n X m eans n blank spaces.

The FORMAT A n m eans n alphanum eric characters.

A / (forward slash) in a Form at statem ents m eans m ove to new line.

W hen the range of a Form at is exceeded without writing all of the item s the form at starts again at the
beginning.

Note: The structure of the binary file is sim ilar to that of the ASCII file but som e of the initial param eters
are re-ordered. For this reason do not attem pt to write a program to read the binary post-
processor files.

2
Parameters:
LUN3 = Logical Unit Num ber of Output Device (File num ber) (=3)
NNP = Num ber of Nodes
NMEM = Num ber of Elem ents
NPRES = Num ber of Nodes saved in .RAS File
NMRES = Num ber of Elem ents saved in .RAS File
IPVERT = see Ruaumoko-2D or Ruaumoko-3D m anual
NBASE = Num ber of Base Excitation degrees of freedom ,
Travelling wave input only, else = 0.
If NBASE = 0
then the displacem ents, velocities and accelerations are Relative to the foundation,
else,
the displacem ents, velocities and accelerations are Total displacem ents, velocities
and accelerations.
NLR = Num ber of Dynam ic Input Excitations
(Earthquake analyses = num ber of com ponents)
(Dynam ic force analyses = num ber of force histories)
(Adaptive Pushover = 1)
(IPANAL = 8 or 9 = num ber of displacem ent histories)
NMODE = Num ber of Mode Shapes available to Dynaplot.
NEP = Num ber of Equations/Node. Ruaumoko-2D = 3, Ruaumoko-3D = 6.
NSPACE = Num ber of Space Dim ensions. Ruaum oko-2D = 2, Ruaumoko-3D = 3
JOUT = Output Flag. Not used any longer. Ruaum oko-2D = 0, Ruaumoko-3D = 0
TK = Tim e Interval between post-processor file write statem ents
TIME = Duration of excitation (Initial input value)
PLOT = 19 term array for graphics inform ation. In Ruaumoko-2D only the first 3 are used
DT = Ruaumoko-2D and Ruaumoko-3D tim e-step
KPOST = Num ber of tim e steps between saves to post_processor file
Ruaumoko-2D = KPA see Ruaum oko2D user m anual,
Ruaumoko-3D = KPOST see Ruaum oko3D user m anual.
N = Num ber of item s written for m em ber I
MPLOT = Packed plot flag for m em bers, a 1 to 6 digit integer.
I,J,K,M are Integer indices

3
Element Data retrieved.

If L = elem ent num ber

NP(1,L) = Node I of elem ent
NP(2,L) = Node J of elem ent
NP(3,L) = Node K of elem ent
NP(4,L) = Node L of elem ent
NP(5,L) = IOUT for Elem ent.
(if = 0 or 1 replaced with num ber of item s/elem ent, else = 0)
(if IOUT is 2 or 3 this elem ent's data is not written to the post-processor file)
NP(6,L) = 5 digit com pacted integer IHYST//ITYPE//LTYPE
IHYST (first 2 digits), 0-49 (Hysteresis rule num ber)
ITYPE (third digit) elem ent sub-type
i.e. 1=Giberson Beam
2=Concrete Beam -colum n
3=Steel Beam -colum n
4=General Beam -colum n
5=Two-Com ponent Beam
6=Variable Flexibility Beam
7=4 Hinge Beam (Ruaumoko-2D)
7=Alternative Concrete Beam -colum n (Ruaumoko-3D)
9=Beam or Beam -Colum n with In-elastic shear
LTYPE (fourth and fifth digits) elem ent type
i.e. 1=fram e m em ber
2=spring m em ber
3=wall m em ber (Ruaumoko-2D only)
4=dam per m em ber
5=tendon m em ber
6=contact m em ber
7=quadrilateral finite elem ent
8=m asonry panel elem ent
9=foundation m em ber
BEND1,BEND2 = Rigid End-block lengths of Fram e elem ents, else 0.0

4
STRUCTURE data saved at each KPOST save step:

a:Ruaumoko-2D.

FT( 1) = TIME (written as two integers, Num ber of whole seconds and Num ber of 1/10000 seconds)
(see note below)
*Earthquakes
IF(IPVERT.GE.0) THEN
FT( 2) = X ground Acceleration
FT( 3) = Y ground Acceleration
FT( 4) = X ground Velocity
FT( 5) = Y ground Velocity
FT( 6) = X ground Displacem ent
FT( 7) = Y ground Displacem ent
*Dynam ic Excitation & 'Adaptive Pushover'
ELSEIF(IPVERT.LT.0) THEN
FT( 2) = First Excitation Value
FT( 3) = 0.0
IF(IPVERT.LE.-2) FT( 3) = Second Excitation Value
FT( 4) = 0.0
FT( 5) = 0.0
FT( 6) = 0.0
FT( 7) = 0.0
ENDIF
FT( 8) = Kinetic Energy
FT( 9) = Dam ping W ork Dissipated
FT(10) = Strain Energy
FT(11) = Applied W ork Done
FT(12) = Plastic W ork (Approxim ate)
FT(13) = Effective Ductility (Only useful in Pushover analyses)
FT(14) = Effective X displacem ent (Only useful in Pushover analysis)
FT(15) = Effective Y displacem ent (Only useful in Pushover analysis)
FT(16) = Total applied X forces
FT(17) = Total applied Y forces
FT(18) = Total applied Z m om ent about origin (X=0,Y=0)

Note: This saving of tim e as two integers m eans that the shortest tim e step that m ay be saved for post-
processing is 0.0001seconds i.e. KPA*DT $ 0.0001 where KPA is the post-processor output step interval and
DT is the analysis tim e-step (this should be adequate for m ost analysts). The earlier versions had trouble
with either long duration records (>1000 seconds) and/or with sm all steps due to the single precision saving
of the data (7 decim al digits). This new version m ay m ean that one gets, for say a 25 second integration, that
DYNAPLO T indicates that it has found only 24.9999 seconds of record, This integer truncation is on no
consequence.

5
b:Ruaumoko-3D

FT( 1) = TIME (written as two integers, Num ber of whole seconds and Num ber of 1/10000 seconds)
(see note below)
*Earthquakes
IF(IPVERT.GE.0) THEN
FT( 2) = X ground Acceleration
FT( 3) = Y ground Acceleration
FT( 4) = Z ground Acceleration
FT( 5) = X ground Velocity
FT( 6) = Y ground Velocity
FT( 7) = Z ground Velocity
FT( 8) = X ground Displacem ent
FT( 9) = Y ground Displacem ent
FT(10) = Z ground Displacem ent
*Dynam ic Excitation & 'Adaptive Pushover'
ELSEIF(IPVERT.LT.0) THEN
FT( 2) = First Excitation Value
FT( 3) = 0.0
IF(IPVERT.LE.-2) FT( 3) = Second Excitation Value
FT( 4) = 0.0
IF(IPVERT.LE.-3) FT( 4) = Third Excitation Value
FT( 5) = 0.0
FT( 6) = 0.0
FT( 7) = 0.0
FT( 8) = 0.0
FT( 9) = 0.0
FT(10) = 0.0
ENDIF
FT(11) = Kinetic Energy
FT(12) = Dam ping W ork Dissipated
FT(13) = Strain Energy
FT(14) = Applied W ork Done
FT(15) = Plastic W ork (Approxim ate)
FT(16) = Effective Ductility (Only useful in Pushover analyses)
FT(17) = Effective X displacem ent (Only useful in Pushover analysis)
FT(18) = Effective Y displacem ent (Only useful in Pushover analysis)
FT(19) = Effective Z displacem ent (Only useful in Pushover analysis)
FT(20) = Total applied X forces
FT(21) = Total applied Y forces
FT(22) = Total applied Z forces
FT(23) = Total applied X m om ent about origin (Y=0,Z=0)
FT(24) = Total applied Y m om ent about origin (Z=0,X=0)
FT(25) = Total applied Z m om ent about origin (X=0,Y=0)

Note: This saving of tim e as two integers m eans that the shortest tim e step that m ay be saved for post-
processing is 0.0001seconds i.e. KPOST*DT $ 0.0001 where KPOST is the post-processor output step
interval and DT is the analysis tim e-step (this should be adequate for m ost analysts). The earlier versions
had trouble with either long duration records (>1000 seconds) and/or with sm all steps due to the single
precision saving of the data (7 decim al digits). This new version m ay m ean that one gets, for say a 25 second
integration, that DYNAPLOT indicates that it has found only 24.9999 seconds of record, This integer
truncation is on no consequence.

6
NODAL POINT data saved at each KPOST (or KPA) time steps:
(see IOUT in m anual to identify which nodes save data)

a:Ruaumoko-2D

I = nodal point num ber

FT( 1) = X displacem ent
FT( 2) = Y displacem ent
FT( 3) = Z rotation
FT( 4) = X velocity
FT( 5) = Y velocity
FT( 6) = Z rotational velocity
FT( 7) = X acceleration
FT( 8) = Y acceleration
FT( 9) = Z rotational acceleration
FT(10) = X applied force
FT(11) = Y applied force
FT(12) = Z applied m om ent
FT(13) = X dam ping force
FT(14) = Y dam ping force
FT(15) = Z dam ping m om ent
FT(16) = X inertia force
FT(17) = Y inertia force
FT(18) = Z inertia m om ent

7
b:Ruaumoko-3D

I = nodal point num ber

FT( 1) = X displacem ent
FT( 2) = Y displacem ent
FT( 3) = Z displacem ent
FT( 4) = X rotation
FT( 5) = Y rotation
FT( 6) = Z rotation
FT( 7) = X velocity
FT( 8) = Y velocity
FT( 9) = Z velocity
FT(10) = X rotational velocity
FT(11) = Y rotational velocity
FT(12) = Z rotational velocity
FT(13) = X acceleration
FT(14) = Y acceleration
FT(15) = Z acceleration
FT(16) = X rotational acceleration
FT(17) = Y rotational acceleration
FT(18) = Z rotational acceleration
FT(19) = X applied force
FT(20) = Y applied force
FT(21) = Z applied force
FT(22) = X applied m om ent
FT(23) = Y applied m om ent
FT(24) = Z applied m om ent
FT(25) = X dam ping force
FT(26) = Y dam ping force
FT(27) = Z dam ping force
FT(28) = X dam ping m om ent
FT(29) = Y dam ping m om ent
FT(30) = Z dam ping m om ent
FT(31) = X inertia force
FT(32) = Y inertia force
FT(33) = Z inertia force
FT(34) = X inertia m om ent
FT(35) = Y inertia m om ent
FT(36) = Z inertia m om ent

8
ELEM ENT data saved at each KPOST (or KPA) time steps:
(see IOUT in m anual to identify which elem ents save data)

a: Ruaumoko-2D

I = elem ent num ber

MPLOT = 5 digit com pacted plot flag
K = Num ber of elem ent Data Item s

FT = 17 item s for Beam s (27 if 4 node Beam s) (21 if inelastic shear)

Axial force, Axial displacem ent, Axial stiffness,
Axial Energy, Axial dam age Index, Mom ent @ 1,
Curvature @ 1, Stiffness @ 1, Energy Flexure @ 1,
Dam age Index@1 Mom ent @ 2, Curvature @ 2,
Stiffness @ 2, Energy Flexure @ 2 Dam age Index@2
Shear @ 1, Shear @ 2
(plus for 4 node beam )
Mom ent @ 3, Curvature @ 3, Stiffness @ 3, Energy @ 3,
Dam age Index@ 3
Mom ent @ 4, Curvature @ 4, Stiffness @ 4, Energy @ 4,
Dam age Index@ 4
(or plus for in-elastic shear)
Shear Displacem ent @ 1, Shear Stiffness @ 1,
Shear Displacem ent @ 2, Shear Stiffness @ 2,
(or plus for in-elastic shear-link)
Link Shear Angle @ 1, Link Shear Angle @ 1,
Shear Flexibility % @ 2, Shear Flexibility % @ 2,

= 15 item s for Springs

Longitudinal force, Transverse Force, Mom ent
Longitudinal Disp., Transverse Disp. Rotation
Long. % Stiffness, Trans.% Stiffness, Rotn. % Stiffness
Longitudinal energy, Tranverse Energy, Rotational Energy
Longitudinal Dam age, Tranverse Dam age, Rotational Dam age

= 13 item s for W alls

Axial force, Axial displacem ent, Axial stiffness,
Mom ent @ 1, Curvature @ 1, Stiffness @ 1,
Mom ent @ 2, Curvature @ 2, Stiffness @ 2,
Shear @ 1, Shear @ 2,
Neutral Axis @ 1, Neutral Axis @ 2

= 6 item s for Dam pers

Longitudinal force, Longitudinal velocity
Transverse force, Transverse velocity
Rotational m om ent, Rotational velocity

= 2 item s for Tendons

Longitudinal force, Longitudinal displacem ent

= 5 item s for Contact Elem ents

Longitudinal force, displacem ent, % stiffness,
Transverse force, displacem ent

= 12 item s for Quadrilaterals

XX Stress, YY Stress, XY stress at Node 1 or I
XX Stress, YY Stress, XY stress at Node 2 or J
XX Stress, YY Stress, XY stress at Node 3 or K
XX Stress, YY Stress, XY stress at Node 4 or L

9
= 15 item s for Masonry Panels
Force, displacem ent, % stiffness for Strut 1
Force, displacem ent, % stiffness for Strut 2
Force, displacem ent, % stiffness for Strut 3
Force, displacem ent, % stiffness for Strut 4
Force, displacem ent, % stiffness for Shear strut

= 24 item s for Foundation Elem ents

For each of the 8 W inkler springs: (2 axial springs, 4 norm al springs and 2 shear springs)
Longitudinal force, displacem ent, % stiffness,
Transverse force, displacem ent, % stiffness,

= 30 item s for Multi-spring Elem ents

Longitudinal force, Transverse Force, Mom ent
Longitudinal Disp., Transverse Disp. Rotation
Long. % Stiffness, Trans.% Stiffness, Rotn. % Stiffness
Transverse shift of neutral axis
For each of the 10 springs that m ake up the m ulti-spring m em ber:
Longitudinal force and Longitudinal displacem ent

= 30 item s for Com pound Spring Elem ents

Longitudinal force, Transverse Force, Mom ent
Longitudinal Disp., Transverse Disp. Rotation
Long. % Stiffness, Trans.% Stiffness, Rotn. % Stiffness
Transverse shift of neutral axis
For each of the 10 springs/dam pers/tendons that m ake up the com pound spring m em ber:
Force and Displacem ent

10
b:Ruaumoko-3D
============

I = elem ent num ber

MPLOT = 5 digit com pacted plot flag

FT = 24 item s for Fram e m em bers (44 if In-elastic shear) (dam age Index is Park and Ang)
Axial force, elongation, % stiffness, energy, Dam age Index,
Mom ent z-z @ 1, curvature z-z @ 1, % stiffness, energy, Dam age Index,
Mom ent z-z @ 2, curvature z-z @ 2, % stiffness, energy, Dam age Index,
Torque, twist, % stiffness, energy, Dam age Index,
Mom ent y-y @ 1, curvature y-y @ 1, % stiffness, energy, Dam age Index,
Mom ent y-y @ 2, curvature y-y @ 2, % stiffness, energy, Dam age Index,
Shear y @ 1, Shear y @ 2,
Shear z @ 1, Shear z @ 2.
(plus for in-elastic shear)
y-Shear Displacem ent @ 1, y-% Shear Stiffness @ 1,
y-Shear Displacem ent @ 2, y-% Shear Stiffness @ 2,
z-Shear Displacem ent @ 1, z-% Shear Stiffness @ 1,
z-Shear Displacem ent @ 2, z-% Shear Stiffness @ 2,
(or plus for in-elastic shear-link)
y-Shear Link Angle @ 1, y-Shear Link Angle @ 2,
z-Shear Link Angle @ 1, z-Shear Link Angle @ 2,
y-Shear Flexibility % @ 1, y-Shear Flexibility % @ 2,
z-Shear Flexibility % @ 1, z-Shear Flexibility % @ 2,

= 30 item s for Spring m em bers

x force, y force, z force,
x m om ent, y m om ent, z m om ent,
x deform ation, y deform ation, z deform ation,
x rotation, y rotation, z rotation,
x % stiffness, y % stiffness, z % stiffness,
x % rotn. stiffness, y % rotn. stiffness, z % rotn. stiffness,
x disp. energy, y disp. energy, z disp. energy,
x rotn. energy, y rotn. energy, z rotn. energy.
x disp. dam age index, y disp. dam age index, z disp. dam age index,
x rotn. dam age index, y rotn. dam age index, z rotn. dam age index.

= 18 item s for Dam per m em bers

x force, y force, z force,
x m om ent, y m om ent, z m om ent,
x velocity, y velocity, z velocity,
x rotation velocty, y rotation velocity, z rotation velocity,
x % stiffness, y % stiffness, z % stiffness,
x % rotn. stiffness, y % rotn. stiffness, z % rotn. stiffness,

= 2 item s for Tendon m em bers

x force, x displacem ent.

=18 item s for Contact Elem ents

x contact force, y friction force, z friction force,
x dam ping force, y spherical force, z spherical force,
x axial displacem ent y lateral displacem ent, z lateral displacem ent,
x axial velocity, y lateral velocity, z lateral velocity,
% x stiffness, % y friction stiffness % z friction stiffness
x axial bearing rise. % y spherical stiffness % z spherical stiffness

= 24 item s for Quadrilateral finite elem ents (forces and m om ents per unit length)
Nxx, Nyy, Nxy, Mxx, Myy, Mxy at Node I
Nxx, Nyy, Nxy, Mxx, Myy, Mxy at Node J
Nxx, Nyy, Nxy, Mxx, Myy, Mxy at Node K
Nxx, Nyy, Nxy, Mxx, Myy, Mxy at Node L

11
= 27 item s for Masonry Panel elem ents
Force, displacem ent, % stiffness for Strut 1
Force, displacem ent, % stiffness for Strut 2
Force, displacem ent, % stiffness for Strut 3
Force, displacem ent, % stiffness for Strut 4
Force, displacem ent, % stiffness for Shear strut
Mxx, Myy, Mxy at Node I (m om ents per unit length)
Mxx, Myy, Mxy at Node J
Mxx, Myy, Mxy at Node K
Mxx, Myy, Mxy at Node L

= 24 item s for Foundation Elem ents

For each of the 8 W inkler springs: (2 axial springs, 4 norm al springs and 2 shear springs)
force, displacem ent, % stiffness,

= 39 item s for Multi-spring Elem ents

x force, y force, z force,
x m om ent, y m om ent, z m om ent,
x deform ation, y deform ation, z deform ation,
x rotation, y rotation, z rotation,
x % stiffness, y % stiffness, z % stiffness,
x % rotn. stiffness, y % rotn. stiffness, z % rotn. stiffness,
y shift in neutral axis,
For each of the 10 springs that m ake up the m ulti-spring m em ber:
Longitudinal force and Longitudinal displacem ent

= 60 item s for Com pound Spring Elem ents

x force, y force, z force,
x m om ent, y m om ent, z m om ent,
x deform ation, y deform ation, z deform ation,
x rotation, y rotation, z rotation,
x % stiffness, y % stiffness, z % stiffness,
x % rotn. stiffness, y % rotn. stiffness, z % rotn. stiffness,
y shift in neutral axis, z shift in neutral axis
For each of the 20 springs that m ake up the m ulti-spring m em ber:
Force and Displacem ent

= 30 item s for External Elem ents

either:
x force, y force, z force,
x m om ent, y m om ent, z m om ent,
x deform ation, y deform ation, z deform ation,
x rotation, y rotation, z rotation,
x % stiffness, y % stiffness, z % stiffness,
x % rotn. stiffness, y % rotn. stiffness, z % rotn. stiffness,
plus 12 zeros, (reserved for future use).
or:
axial force, z m om ent end 1, z m om ent end 2,
torque, y m om ent end 1, y m om ent end 2,
x axial deform ation, z curvature end 1, z curvature end 2,
x rotation (twist), y curvature end 1, y curvature end 2,
x axial % stiffness, z flex. stiff end 1 %, z flex. stiff end 2 %,
x % rotn. stiffness, y flex. stiff end 1 %, y flex. stiff end 2 %,
plus 12 zeros, (reserved for future use).

12
Sample FORTRAN code:
C
C ***********************************************************************
C Typical write statements used in RUAUMOKO-2D and RUAUMOKO-3D
C ***********************************************************************
C
C Initial Structure data
C
TK = DT*FLOAT(KPA)
C *Are ALL nodes saved to the post-processor file?
C *if not, no point in saving mode shapes as
C *DYNAPLOT will not be able to plot them.
IF(NPRES.LT.NNP) NMODE = 0
C *Parameters (1 line)
WRITE(LUN3,'(9I5,5X,2F10.4)') NNP,NMEM,NPRES,NMRES,IPVERT,NBASE,
* NLR,NMODE,NEP,NSPACE,JOUT,TK,TIME
C *Plot data (2 lines)
WRITE(LUN3,'(1P12E10.3)') (PLOT(I),I=1,19)
C *Nodal Coordinates
C *RUAUMOKO-2D (X & Y per node, 6 nodes/line)
C *RUAUMOKO-3D (X,Y & Z per node, 4 nodes/line)
WRITE(LUN3,'(1P12E10.3)') ((CORD(I,J),J=1,NSPACE),I=1,NNP)
C *Element data: (2 elements per line)
WRITE(LUN3,'(6I5,1P2E10.3,10X,6I5,2E10.3)')
* ((NP(J,I),J=1,6),BEND(1,I),BEND(2,I),I=1,NMEM)
C *Natural Frequencies and Mode Shapes
IF(NMODE.GT.0) THEN
WRITE(LUN3,'(1P12E10.3)') (W(I),I=1,NMODE)
DO 10 K=1,NMODE
WRITE(LUN3,'(1P12E10.3)') ((SHAPE(I,J),I=1,NNP),J=1,NEP)
10 CONTINUE
ENDIF
C
C For each of output steps every KPOST time-steps starting at TIME = 0.0
C
C *Structure data (RUAUMOKO-2D) either
WRITE(LUN3,'(A4,I5,I6,1P11E10.3/5X,6E10.3)')
* 'TIME',I1,I2,(FT(I),I=2,18)
C *Structure data (RUAUMOKO-3D) or
WRITE(LUN3,'(A4,I5,I6,1P11E10.3/5X,12E10.3/5X,E10.3)')
* 'TIME',I1,I2,(FT(I),I=2,25)
C *I1 = Number of whole seconds,
C *I2 = Number of 1/10000 seconds
C *Node Data: For Each Node saved
DO 20 I=1,NPRES
C *RUAUMOKO-2D (1 line/node) either
WRITE(LUN3,'(I5,1P12E10.3)') I,(FT(J),J=1,12)
C *RUAUMOKO-3D (3 lines/node) or
WRITE(LUN3,'(I5,1P12E10.3/5X,12E10.3/5X,12E10.3)')
* I,(FT(J),J=1,36)
20 CONTINUE
C *Element Data: For Each Element saved
C *(1 to 3 lines/element)
DO 30 I=1,NMEM
N = NP(5,I)
IF(N.GT.0) THEN
WRITE(LUN3,'(I5,I10,1P11E10.3/5X,12E10.3/5X,12E10.3)')
* I,MPLOT,(FT(J),J=1,N)
ENDIF
30 CONTINUE
C
C ***********************************************************************

13
 TINYCLIP
An Interactive Command Processor.

Athol J. Carr

Traditional Fortran program s were run in a batch m ode with the input data com ing from an input file where the
data was set out in a fixed form at as described in som e form of user docum ent. Modern program s designed for
use on personal com puters or workstations generally operate in an interactive m ode and the stilted fixed form at
does not lend itself to interactive operation. Although Fortran77 introduced the concept of a Free Form at input
this does not provide an interactive input as the data on a line m ust be of the correct type, i.e. if the input variable
is of type integer then an integer num ber m ust be provided. In an interactive m ode the program m ust be able
to accept the typed input and then exam ine it to determ ine what action to take. If the input is not of the expected
form then the program m ust be able to prom pt for the correct inform ation. However, the program should be
capable of running in a batch, or non interactive, m ode as well.

TinyCLIP is an interactive com m and processor for use in program s in written Fortran77, or later versions of
Fortran, and which require to be able to interactively process input data. In this interpreter whatever is typed in
by the user is accepted by the reader. The user input is analysed by an item parser and the results placed in an
item table. For exam ple, if the user types

SET VALUE 3.33333333

then a reasonably looking item table would be

Item Type Value

1 Character SET

2 Character VALUE

3 Floating 3.33333333

The parser m ay perform transformations of the input. To illustrate this point, suppose you now type

set value = (10/3)

but that the resulting item table is identical. Three transform ations have been perform ed:
1. Lower case letters have been converted to upper case. (to sim plify keyword testing);
2. The equals sign has been treated as a "noise character"; and
3. The item (10/3) has been processed by a "calculator" routine that converts it to 3.33333333.

INTERFACE SPECIFICATION.

Before getting into the im plem entation of TinyCLIP let us look at the interface. In what follows, the term processor
denotes the program that calls TinyCLIP to get its com m and input from the user.

Asking for Commands

The processor asks for a com m and by invoking the "get the next com m and" entry point CLREAD as illustrated
by

CALL CLREAD(' Enter Com m and : ',' ')

CLREAD has two character-string argum ents. The first argum ent is the com m and prom pt. If you are running
the program interactively, the following prom pt text will appear on the screen:

Enter Com m and :

and the reader will wait for your response. The second argum ent is the com m and 'splash' which m ay be used
to provide extra inform ation to the user. If the splash is non-blank then it will be displayed above the prom pt.
On return from CLREAD you are entitled to assum e that the user has typed something that looks like a
com m and. If the user just types a carriage return, or a blank line, CLREAD will keep on prom pting. The policy
"don't com e back until you have som ething to show" is (for psychological reasons) usually the right one in
interactive work.

Accessing Item Information

On return from CLREAD the alleged com m and is nicely parsed in internal tables. Now your job is to extract the
data from the tables so you can take a look at it and proceed to execute the com m and. TinyCLIP provides seven
Fortran functions for inform ation retrieval;

Function Type

ICLNIT() INTEGER

CCLTYP(I) CHARACTER*1

CCLSEP(I) CHARACTER*1

CCLVAL(I) CHARACTER*(*)

ICLVAL(I) INTEGER

FCLVAL(I) REAL

DCLVAL(I) DOUBLE PRECISION

The function ICLNIT returns the num ber of item s in the last com m and read.

The function CCLTYP returns the type of the ith item as follows: A for character string (alphanum eric item ), I for
integer, and F for floating point.

Item s are separated by blanks, com m as or equals signs. For som e processors whose input m ay contain num eric
lists it is convenient to be able to test for item separators so that

1234 1, 2, 3, 4

are effectively different. CCLSEP returns the separator after the ith item if one was found, otherwise it returns
a blank.

The four functions nam ed xCLVAL return values of the ith com m and item in the type im plied by the function
nam e. If the item is alphanum eric, CCLVAL returns its left-justified value appropriately truncated or blank filled.
If the item is integer, ICLVAL returns its integer value. If the item is floating point, FCLVAL returns its single
precision value and DCLVAL returns its double precision value.

Mixed m ode retrieval is acceptable for num eric item s, and the usual Fortran conventions apply. For exam ple,
if the 5th item is 7.4, ICLVAL(5) returns 7; and if the 8th item is integer 46, DCLVAL(8) returns 46.0D0. If
CCLVAL is tried on a num eric item , it returns blank, and if a num eric function is tried on an alphanum eric item ,
it returns zero.

Som e points are worth noting. Character strings are upper-cased unless protected with apostrophes and the
string is then treated as a single item . All characters of an apostrophe delim ited string are significant, including
blanks, and an apostrophe m ay be represented by repeating it. Arithm etic expressions are delim ited by
parentheses and evaluated according to the usual Fortran rules (but ^ is the exponentiation operator instead of
**). Blanks inside an arithm etic expression are ignored.

The m axim um length of a line is 132 characters and the m axim um num ber of item s on a line is 100. A line m ay
be term inated by placing an isolated exclam ation sign ! on the line. Anything on the line following the exclam ation
sign is ignored by CLREAD.
Prompts

The character string for the prom pt should not be so long that insufficient space is left on the line for the
response. The first character in the string is a carriage control, a blank m eans that the prom pt is displayed on
the next line on the screen, a 1 causes one blank line to be inserted ahead of the prom pt and a 2 causes two
blank lines to precede the prom pt.

If part of the prom pt contains item s inside enclosing square brackets i.e. [ Default1 Default2 ] then the item s
inside the brackets are used as default values should the user just hit the carriage return or supply a blank line.
If any non blank data is supplied as part of the user response then the default values are ignored. You cannot
replace part of the list of default values, it is all or nothing. This feature m ay be useful in som e program s where
com m only used responses can be arranged as defaults to m inim ise typed input from the user. The prom pt is
not displayed if the processor is running in a "batch" m ode or if the input is com ing from an ADD file which is
described in the section on Directives below.

Splashes

If inform ation about the expected response to a prom pt is required this can be supplied in the splash character
string. The first character in the string is used as a carriage control in the sam e way as for the prom pt above.
A new line m ay be specified by the double am persand &&. Such an && m ust be preceded by at least one blank
character and followed by at least one character (blank or otherwise) prior the end of the string.

If you wish to display a splash other than as part of asking for a com m and this m ay be done by calling the
subroutine CLSHOW

CALL CLSHOW (' any splash you want')

If the inform ation is com ing interactively from the keyboard then the splash will appear on the screen. If the
inform ation is being read in a "batch" m ode, or from an ADD file, then the splash, like the prom pt in CLREAD will
not be displayed.

Comparing Commands

Tinyclip has a logical function CMATCH which m ay used to com pare com m ands. This function has two character
string argum ents. The first, key1, is the alleged com m and and key2 is the com m and against which key1 is
tested.

Key1: The alleged key, all characters m ust be upper case. It m ay contain m asking characters % and * with the
usual VAX m eanings, however, * is only acceptable as a first or last character. Key1 is term inated by a
blank, period, or string exhaustion.

Key2: Internal key, consisting of a root+extension. The root m ust be in upper case and the extension is in lower
case or separated by a ^. Key2 is term inated by a blank, a period, or string exhaustion.

CMATCH first com pares the root characters, and reports failure if no m atch. If root m atch is achieved, it
continues com paring extension characters until: (a) a m ism atch is found; (b) either key is exhausted; or (c) a
blank is found in either key.

If a m atch is found CMATCH is .TRUE. otherwise .FALSE. For exam ple;

CMATCH('COPY','COPy') --> .TRUE.

CMATCH('COPY','COPyall') --> .TRUE.
CMATCH('CO' ,'COP^Y') --> .FALSE.
CMATCH('COPOUT','COPy') --> .FALSE.
CMATCH('COPY','CONnect') --> .FALSE.
CMATCH('*OP*','COPy') --> .TRUE.

Comments

Any line beginning with an isolated asterisk (*) is treated as a com m ent line. This line is then output to the
standard output device, the screen in interactive m ode or, by default, logical unit num ber 6 if in "batch" m ode.
If the processor is to m ake use of the com m ent feature then a call to subroutine CLINIT(LPU) should be m ade
before any calls to CLREAD. The integer LPU is the logical unit num ber for the processor's listed output if it is
different from the default value. If there is an isolated (preceded and followed by blanks) exclam ation sign (!) On
a line then the exclam ation sign and anything else on the line is ignored by TinyCLIP. This is, in effect, a m eans
of term inating the line and if the data is com ing from a $add text file, then notes m ay be added to the line after
the ! as user inform ation. If the exclam ation sign is the first character on the line (a preceding blank is not needed
in this case) then the whole line is ignored by TinyCLIP.

Separators

Separators between item s on a line are blanks, com m as (,) or equal signs (=). Care m ust be taken that com m as
are not used as decim al points, as is com m on practice in parts of Europe. TinyCLIP, as is norm al in FORTRAN,
uses the stop (.) as the decim al point.

Directives

TinyCLIP recognises a series of Directives from the user. These com m and TinyCLIP to undertake specified
actions. The Directive m ust be the first com m and on the line and the first character of the directive is the $ sign.
This m eans that the processor m ay not use the $ as the beginning of any other com m and as it will be taken as
the beginning of an illegal Directive. Som e directives are followed by a file nam e, and path unless it is in the
users current directory. The file nam e and path m ust follow the file nam e convention of the users operating
system .

$TYPE <filenam e>. In interactive m ode, this will display the contents of <filenam e> on the screen. In
"batch" m ode, it is ignored.

$ADD <filenam e>. Transfers input from the interactive user, or "batch" input file, to the file <filenam e>. On
exhaustion of the file, or encountering the Directive $EOF or $STOP in the ADDed input
file, input returns to the original interactive user input, or "batch" input file, as
appropriate.

$STOP or $EOF If the input is com ing from an ADD file, see above, input is returned to the interactive
or original input file. If it comes from the original input file, or the interactive user
keyboard, the processor is term inated. This stops your program from any further
execution.

$ECHO This causes every input line to CLREAD to be echoed on the screen.

$NOECHO Turns off the above ECHO.

$LOG <filenam e> All responses to CLREAD are logged into the nam ed file. This enables a copy of the
input to be saved to enable future input to the program to be provided by the $ADD
Directive. This m eans that large data files m ay be built up using the interactive features
of TinyCLIP and then be ready for later "batch" processing or to save re-keying in later
interactive runs. Directives them selves are not logged.

$ENDLOG Stops Logging of data above. Inserts a $EOF Directive at the end of the Log file.

$DLOG Rem oves last record from the LOG file.

$HELP Provides HELP on the TinyCLIP Com m and Processor. This is in addition to any HELP
files that m ay be provided in by the program itself. The T inyCLIP Help file covers
separators, file nam es, num bers and expressions, strings, directives, allowable
characters etc.

If Directives are likely to be used in your program you should insert a call to subroutine CLTIDY (which has no
argum ents) at the end of your program . This ensures that all ADD or LOG files are closed before the program
term inates. Som e operating system s do not save a file which is created within a program if it is then not closed
prior to the program execution term inating.

If the program wishes to rem ove the last record stored in a LOG file, for instance when the program recognizes
that the input was erroneous then that record m ay be rem oved by a call to subroutine CLDLOG (which has no
argum ents) and which Backspaces the LOG file. If Logging is not in progress no action is taken by the call to
CLDLOG.
Copying The Command Line

If a copy of all or part of the input com m and line is required then this m ay be achieved by a call to the subroutine
CCLGET. The subroutine has two argum ents, the first is an integer N which is the num ber of characters from
the com m and line that you want and the second is a character string variable in which the copy of the input line
is returned. The length of the character string m ust be greater than or equal to N.

M essages

Another powerful language extension vehicle is the message. A m essage is a com m and or directive subm itted
by the processor. To give an exam ple, suppose that when the processor starts it realizes that it is running in
batch m ode and wants to turn on the echo printing. To do this it calls a 'm ailbox' entry point CLPUT and places
a m essage containing an ECHO directive:

CALL CLPUT('$ECHO')

The argum ent of CLPUT is a character string containing the m essage text. The m essage is processed exactly
as if it was a com m and typed by the user, and the net effect is that the echo is turned on. The m essage provides
an elegant tool to achieve input-device independence.

Holding Input

Suppose that in running the processor a situation is encountered where a com m and is discovered which really
should have been detected further up your program tree and to prevent passing flags back to say that this
com m and has already been found you m ay call the CLPUT with a blank text to retain the current input in the
buffer to be read at the next prom pt in the processor. On the next call to CLREAD this input is read from the
buffer instead of CLREAD prom pting for the norm al input.

As an exam ple, suppose SOMEFLAG is the key-com m and that is unexpected in the current input

CALL CLREAD(' Next Data :',' ')

IF(CMATCH(CCLVAL(1),'SOMEFLAG') THEN
CALL CLPUT(' ')
GO TO 100
ELSEIF(.........

The current program m odule should com plete its tasks and then proceed to the part of the program in which that
particular com m and SOMEFLAG is expected. The next call to CLREAD will not display the prom pt as TinyCLIP
has been inform ed that the appropriate response is already in the com m and buffer.

Utilities

There are several utility functions and subroutines that form part of the TinyCLIP library and which the
program m er m ay find helpful in other parts of his/her program .

The integer function LENETB(C) returns the length of the character string C up to the last non-blank character.
The Fortran intrinsic function LEN(C) returns the defined length of the string, blanks and all.

Subroutine TOUPPE(C) converts all lower case alphabetic characters in the character string C to upper case.

Subroutine FINDBI(MODE) determ ines the form of input for the processor. This should not be required for any
user of TinyCLIP as it, on the first call to CLREAD calls FINDBI. If the processor is being in run in an interactive
m ode the integer variable MODE equals 2, while if the processor is being run in a "batch" m ode, MODE equals
0.

The Logical function CLKEYB() returns the value .TRUE. if the program is being run interactively with the input
from the keyboard, otherwise, if the program is being run in "batch" m ode or the input is com ing from an ADD
file then the returned value is .FALSE.

The Integer function ICLFIL() returns the value of the logical unit num ber of the current input device, 0 from the
keyboard, 5 if the input is in 'batch' m ode and 99 if from an ADD file.
Calculator

TinyCLIP has a built-in reverse-polish-notation (rpn) calculator that enables arithm etic expressions to be read
as input num bers. The exam ple on page 1 shows how this m ay be used. The input line was

set value = (10/3)

The first two item s are of type character and the equals sign, like blanks, is taken as a separator and the third
item is read as the num erical value 0.3333. The arithm etic expressions m ust be enclosed with m atching
parentheses () and the item s enclosed within the parentheses m ust satisfy the rules for the calculator input. Any
included parentheses m ust be in m atching pairs. Invalid expressions are taken as character strings and have
a num erical value of zero. Blanks inside the expressions are ignored.

The operators are:

+ for addition,
- for subtraction,
* for m ultiplication,
/ for division,
% for integer division,
^ for exponentiation.

TinyCLIP uses Reverse Polish Notation for carrying out the operations and the norm al FORTRAN priorities for
precedence of operations. The order of operations m ay be controlled by enclosing sub-operations in parentheses.

Exam ples;
(10/3+2^3) = 11.333333333
(10.0-2*(10/3+1)) = 1.333333333
(10.0-2*(10%3+1)) = 2.0
(16.0^0.5 + 2) = 6.0

Logical Unit Numbers

In interactive m ode the logical unit num bers for both input and output are 0. If the processor is running in batch
m ode then the input logical unit num ber is 5 and the output logical unit num ber is 6. The ADD files are read from
logical unit num ber 99 and the LOG files are created on logical unit num ber 98. The user should be careful in
the assignm ent of logical unit num bers to avoid 98 and 99. Logical unit 6 m ay be quite safely used for norm al
output as it will cause no conflict with TinyCLIP but do not use it for other input/output purposes. The com m ent
lines, and any error m essages, are output to the output units 0 or 6 as outlined above. The com m ent lines m ay
be directed to another output device by a call to subroutine CLINIT as was described earlier under the heading
Com m ents where this other logical unit should be opened by the processor.

If TinyCLIP is running interactively under a UNIX operating system and if the processor's standard output is being
directed to a file then the logical unit num ber of that output file should be different to that of the default standard
output stout (stout is usually FO RTRAN file 6). If the default logical unit num ber of stout is used then the
prom pts and splashes, which are m eant to be sent to the screen, are also captured by the standard output file
and the prom pts are invisible to the user at the keyboard.

Unix and Linux Operating System s

Users on unix or linux operating system s should be careful when specifying file nam es for the $add and $log
directives. TinyCLIP upper-cases all character strings and as file and directory nam es are case-sensitive in these
operating system s the user should enclose files nam es in quotes to retain the case of alphabetic characters in
the nam es.
HELP Files

TinyCLIP provides an easy way for the program m er to add HELP files to his processor. The program m er has
to write a subroutine C LHELP(TOPIC) which has as its only argum ent the character string TOPIC. This
subroutine has no calls from within his/her own program but will prevent the Default subroutine CLHELP being
loaded from the TinyCLIP library. This default subroutine supplied by the TinyCLIP library just responds by saying
that there is no help available from the program .

If the response to the CLREAD prom pt is HELP or ? followed by an optional character string TOPIC then
TinyCLIP goes to the CLHELP subroutine, attem pts to m atch the TOPIC, if present it then writes to the screen
the inform ation about that topic, and then prom pts for any other TOPIC. If the user responds with a carriage
return (blank line) TinyCLIP returns to CLREAD which again displays the original prom pt. An exam ple of a help
file is shown on the next page. All calls to the HELP routine or any responses to prom pts within the HELP files
are not Logged in the LOG files if Logging is in process.

If the program m er wishes he/she m ay provide a default help topic by a call to subroutine CLHINT('topic') where
'topic' is a topic which should exist in the HELP file. Any call to HELP or ? without a topic will use the topic
provided in the latest call to subroutine CLHINT. If there are no suitable topics for later input then a call should
be m ade to CLHINT(' ') which will provide no default hint for future calls to HELP.

It is recom m ended that the inform ation supplied on a topic not exceed eighteen or so lines as this is all that m ay
be displayed without the first lines disappearing as the request for further topics appears at the bottom of the
screen. If further inform ation is required to be presented then there should be a request for the reader to hit the
ENTER or RETURN key in order to proceed to the next screenful of inform ation.

Acknow ledgement and Reference

The original form of the TinyCLIP package cam e from a paper "A com m and reader for interactive program m ing"
by Carlos A. Felippa, Engineering Com putation, Vol 2, No. 3, Septem ber 1985, pp203-238.
Help File Example;

SUBROUTINE CLHELP(TOPIC)
C
C ******************************************************************
C HELP FILE
C
C Programmer: Athol J. Carr
C Date/Version: 16-JUL-1995/1.0
C ******************************************************************
C
CHARACTER TOPIC*(*),CCLVAL*20
LOGICAL CMATCH
EXTERNAL CCLVAL,CMATCH
C
10 IF(TOPIC.EQ.' '.OR TOPIC.EQ.'TOPIC') THEN
CALL CLSHOW('1Help is available on the following topics;
* && ADD, ALTER, SUBTRACT, ...
* && MULTIPLY, .... ')
ELSEIF(CMATCH(TOPIC,'ADd') THEN
CALL CLSHOW('1ADD adds Matrix A to Matrix B...')
ELSEIF(CMATCH(TOPIC,'ALter') THEN
CALL CLSHOW('1ALTER modifies the Matrix A in such...)
ELSEIF(CMATCH(TOPIC,'...) THEN
CALL CLSHOW('1........
* && ........
* && ....... ')
CALL CLREAD(' Hit ENTER to [continue] :',' ')
CALL CLSHOW('1......
......
ELSE
CALL CLSHOW('1No Help is available on this Topic')
TOPIC = ' '
GO TO 10
ENDIF
CALL CLREAD('1HELP topic ? [Quit] : ',
* '1Type TOPIC for list of Topics.')
TOPIC = CCLVAL(1)
IF(.NOT.CMATCH(TOPIC,'Quit')) GO TO 10
C
100 RETURN
END