Induction Book

Ruaumoko Manual
Volume 1:
Theory
Author:
Athol J. Carr
Civil Engineering
Department of Civil Engineering COMPUTER PROGRAM LIBRARY
Program name:
RUAUMOKO
Program type:
Inelastic Dynamic Analysis
Program code:
ANSI Fortran77
Author:
Athol J Carr
Date:
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 programs RUAUMOKO-2D, RUAUMOKO-3D, DYNAPLOT, COMBPLOT, SPECTRA, HYSTERES,
SIMQKE, 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 problems in running the programs contact,
Prof. Athol J. Carr,
Department 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 (Home Residence)
FAX +64 3 364-2758 (Department of Civil Engineering)

(Note: +64 = New Zealand., 3 = South Island Area Code)
Electronic mail; a.carr@civil.canterbury.ac.nz
or athol.carr@canterbury.ac.nz

i
Table of Contents
1 INTRODUCTION .................................................................................................................................. 1
2 MODELLING ........................................................................................................................................ 1
3 MASS MATRIX ..................................................................................................................................... 2
4 DAMPING MATRIX .............................................................................................................................. 3
4.1 Rayleigh or Proportional Damping Models .............................................................................. 4
4.2 Caughey Damping ................................................................................................................... 6
4.3 Effects of Different Damping Models .................................................................................... 10
4.4 Recommendation.....................................................................................................................14
5 STRUCTURAL MEMBERS ................................................................................................................ 18
5.1 Frame Members .................................................................................................................... 18
5.2 Spring Members .................................................................................................................... 21
5.3 Damping or Dash-pot Members ............................................................................................ 22
5.4 Constant-Force and Active-Tendon Members ...................................................................... 22
5.5 Contact Members .................................................................................................................. 23
5.6 Quadrilateral Finite Elements ................................................................................................ 24
5.7 Masonry Panel Elements ...................................................................................................... 25
5.8 Foundation or Ground Elements ........................................................................................... 26
5.9 Structural Wall Members........................................................................................................ 27
5.10 Five Node Definition of One Dimensional and Two Dimensional Members ......................... 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 Displacement Excitation ....................................................................... 38
7.4 Dynamic 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 Without Mass .......................... 44
9 TIME-HISTORY INTEGRATION ........................................................................................................ 46
9.1 Newmark 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-Format Input ................................................................................................................. 53
12.2 Units ...................................................................................................................................... 53
12.3 Numbering ............................................................................................................................. 53
ii
13 RESULTS ........................................................................................................................................... 54
13.1 Initial Input Echo .................................................................................................................... 54
13.2 Static Analysis ....................................................................................................................... 54
13.3 Modal Analysis ...................................................................................................................... 54
13.4 Dynamic Time-History ........................................................................................................... 54
14 SIGN CONVENTIONS ....................................................................................................................... 55
14.1 Nodes - Displacements and Forces ...................................................................................... 55
14.2 Frame and Foundation Members Displacements and Forces ........................................... 55
14.3 Spring, Damper, Tendon and Contact Members .................................................................. 56
14.4 Quadrilateral Finite Element .................................................................................................. 57
14.5 Masonry Panel Elements ...................................................................................................... 57
15 GRAPHICS ......................................................................................................................................... 58
15.1 On-Screen Graphics ............................................................................................................. 58
16 DUCTILITIES ..................................................................................................................................... 59
16.1 Giberson Beams and Member Ductility ................................................................................. 59
16.2 Beam Column Members ....................................................................................................... 64
17 DAMAGE INDICES ............................................................................................................................ 65
18 ENERGY ............................................................................................................................................ 66
19 REFERENCES ................................................................................................................................... 67
The following sections are numbered separately:
Examples for the use of the program Ruaumoko-2D
Information on the structure of the ASCII format post-processor files.
Information on the command processor TINYCLIP used by all the programs in the Ruaumoko suite of
programmes.
1
RUAUMOKO
The Maori God of Volcanoes and Earthquakes
Athol J Carr.
Maori mythology records that Ruaumoko was the last of a family of seventy, the son of Rangi, the Sky-father, and
Papa, the Earth-mother. He was still at the breast when the Earth-mother was turned over on her face by her
other sons to improve the weather conditions, and was thus carried under. He is stated to be inimical to man 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 time-history response of non-linear general
two-dimensional and three-dimensional structures to ground accelerations, ground displacements or time
varying force excitations. The program may also be used for static or pushover analyses of structures.
2 MODELLING
Several different options are available for the modelling of the Mass, Damping and Stiffness matrices for the
structure. The user is expected to use those most appropriate to the form of structural frame that is being
analysed. The technical literature has very scant reference to the modelling of non-linear structures and some
of the references quoted in this manual may help the new or inexperienced user of the program.
The program has a wide variety of modelling options available to represent the structure and its supports and
interactions with adjoining structures. The mass representation is via lumped or kinematically consistent mass
matrices.
The damping exhibited by the structure can be modelled by the commonly assumed Rayleigh damping models
or by a range of models aimed to give a better representation of the variation of fractions of critical damping with
frequency as well as options for different levels of damping in different parts of the structural system.
There are a wide variety of members available to represent the structural system such as frame type members,
quadrilateral finite element members and special members to represent special effects such as spring and
contact or impact members to represent contact between adjoining structures. There are also foundation
members to represent soil-structure interaction effects and to represent through-soil coupling between adjoining
structures. There is a large number of different hysteresis rules available that may be used to represent the force-
displacement relationships in the different frame, spring, contact and foundation members mentioned above.
There are a wide range of time-history excitations that may be applied to the structure. The excitation may be
in the form of ground accelerations and these may be applied as a rigid-body ground motion or as a travelling
wave acceleration history. The input may be in the form of time-varying dynamic loading histories or in the form
of ground displacement histories. There are also provision for conventional push-over analysis or with an
adaptive push-over analysis for both monotonic loading or as a form of cyclic excitation.
2
3 MASS MATRIX
The mass of the structure is input in the form of weights and internally converted by the program to mass units
by dividing the weights by the acceleration of gravity. The mass may be provided by both specified nodal weights
or by member weight/unit length or element material density. Nodal weights will contribute to only the diagonal
terms of the mass matrix where the terms 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-dimensional analysis where the frame
being analysed is flanked by adjoining frames which carry vertical loads but have relatively insignificant lateral
stiffness. In this case the vertical inertia is associated only with that of the frame being analysed while the
horizontal inertia has to represent the sum of the inertia contributions of all frames being supported, in the lateral
direction, by the frame being analysed.
The member contributions to the mass matrix may take one of three forms, governed by the variable IPCONM
in the first parameter line of the input data.
There is a Lumped mass representation where contributions are made to the diagonal terms associated with the
three translational degrees of freedom at each end of the member or to all four nodes for quadrilateral or panel
elements with no contribution to the rotational degrees of freedom.
The Diagonal mass representation is the same as the Lumped model above except that the contribution to the
rotational degrees of freedom is equal to the diagonal term of the appropriate consistent mass matrix of the
member concerned for beam, beam-column and wall elements. [see Cook, 1981]
The third option is the Consistent mass representation using the kinematically equivalent mass matrix [Clough
1993] where inertia forces are associated with all degrees of freedom. This will result in a mass matrix with the
same banded skyline form as that of the stiffness matrix.
The Consistent mass model requires a greater computational effort in the multiplication by the nodal
accelerations to get the inertia forces at each time-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 masses are those from the input nodal masses there is no difference in the actual mass matrices for
the structure though the consistent mass option would involve the extra cost of multiplying all the zero terms
within the matrix skyline of the associated stiffness matrix when computing the inertia forces.
The mass matrix used for the mode shape and frequency analysis is a diagonal mass matrix. As the computed
free-vibration frequencies are only used for checking purposes and for computing the damping matrix this is of
little consequence. To use the consistent matrix would require a double eigenvalue solution or the Cholesky
decomposition of the mass matrix. The first approach is computationally expensive and the second is not possible
if there are any degrees of freedom without mass as the matrix would then be singular. If a Rayleigh damping
matrix is being specified then the frequencies are used to compute the contributions of both the mass and
stiffness matrices to the damping matrix. If the damping matrix is formulated using the approach of Penzien and
Wilson then all mode shapes and frequencies of free-vibration must be computed. Once the step-by-step time
integration is started, then the specified form of the mass matrix, Lumped, Diagonal or Consistent, is used for
all subsequent computational steps.
If rigid floor diaphragms are being used in the modelling of three dimensional structures then the master node
of the floor should be located at the centre of mass of the floor as during the modal analysis the mass matrix is
diagonalized. The master node should also be at the centre of mass if a lumped or diagonal mass matrix is being
used as there is then no way of expressing the mass coupling between the rotational and translational degrees
of freedom.
3
Figure 1 Rayleigh or Proportional Damping Model
4 DAMPING MATRIX
There are several damping model options available within the program. The traditional approach has been to use
a Rayleigh or Proportional damping model where the structures damping matrix C is given by
where M and K are the mass and stiffness matrices for the structure. The coefficients " and $ are computed to
give the required levels of viscous damping at two different frequencies, most commonly those of the first and
second modes of free vibration.
Rayleigh damping may be modelled proportional to the tangent stiffness matrix or the initial stiffness matrix.
Variable ICTYPE in the first line of the input data controls the selection of the damping model. As a general guide
the user should endeavour to ensure that the fraction of critical damping in the highest modes is less that 100
percent. RUAUMOKO computes the fractions of critical damping at all frequencies for the selected damping
model. The coefficients " and $ may also be specified directly by the user.
Work by Crisp [Crisp 1980] showed that high levels of viscous damping in the high modes of free vibration of a
structure has a marked 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
damping to reduce. However, it appears that this reduction of the damping partially compensates for the
excessive higher mode damping associated with the Rayleigh damping model. With tangent stiffness damping
the fractions of critical damping in the structure tend to remain more constant as the stiffness of the structure
reduces whereas the constant mass and initial stiffness damping contributions imply increasing fractions of critical
damping 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
dynamic equilibrium is required as the non-linearity of the structure precludes the use of super-position and hence
any modal methods such as the use of response spectra techniques. This makes it difficult for the engineer in
that the structure must be analysed for all the load cases simultaneously as the separate gravity and seismic
4
excitation responses cannot be obtained and combined for alternate excitation directions as is traditionally used
in seismic design.
In inelastic structures various hysteresis rules are used to represent the inelastic behaviour of the member
actions, such as the moment-curvature relationships in beam members. These non-linear rules allow for the
energy dissipation due to the non-linearity of the members and although these members do not go through very
many complete hysteresis loops within a single earthquake excitation the large forces associated with these
member hysteresis loops means that a considerable amount of energy is removed from the structural response.
However, these hysteresis models do not, in general, account properly for the energy removed from the system
by small cycle oscillations within the structure. Even structures that remain elastic show a damped response and
the effect of this low level damping in the structure has a marked effect of the response of the structure. An
examination of any earthquake response spectrum will show that even small amounts, i.e., 2 to 5%, of critical
damping will significantly reduce the response of the structure. Some suitable damping model is required in the
analysis to represent this decay. Whether the damping in the structure is actually viscousor hysteretic is
something that has yet to be determined, but in the meantime it is generally assumed to be a viscous damping
mechanism. This is usually justified in that as the damping forces are assumed to be small any error due to this
mathematically convenient assumption is not very significant in the response. This appears to be reasonably well
justified in terms 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 damping model have had on the inelastic responses of framed structures. Most
analysts assumed that if they specified say 5% of critical damping at two modes then their structure had
effectively 5% of critical damping. It was found in 1979 on examining the response of some framed structures
that something appeared to be seriously wrong with joint equilibrium. At an interior joint in the frame, the two
girders framing into the joint had yielded with elasto-plastic yield moments of approximately 1000 kNm each and
yet the sum of the column moments at the joint was of the order of 3000 kNm. The joint appeared to have an out-
of-balance moment of approximately 1000 kNm. On modification of the program to compute and output the joint
forces and moments associated with the damping matrix, the 1000 kNm was found to be a damping moment at
the joint.
Crisp [Crisp, 1980] showed that this frame had approximately 300% of critical damping in its highest modes and
that the large damping moments were associated with large local rotations relative to the lateral displacements
as a consequence of the local yielding of the members connected to the joint in question. Since that research
work we have strongly recommended that when a Rayleigh damping model is being used the frequencies at
which damping is specified must be chosen to ensure that the highest modes of free-vibration in the structure
are sub-critically damped.
In more recent times users of inelastic analyses have reported large apparent losses of equilibrium even in push-
over analyses of simple two member structures by step-by-step dynamic analysis where the damping moments
and forces have been found to reach about 50% of the moment 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 terms would not be a problem. Once
yielding occurs the deformations are often very localized resulting in relatively high local deformation velocities.
4.1 Rayleigh or Proportional Damping Models
The traditional damping model available in most step-by-step or time-history programs is the Rayleigh or
Proportional damping model.
The reason for its popularity is that it uses matrices that the analysis already has computed and requires only the
computation of the two coefficients " and $ in order to form a damping matrix so that the analysis may be carried
out. In many of the programs it is left to the user to estimate the two frequencies at which the required amount
of damping is specified in order to evaluate the two coefficients. Assuming that the properties of orthogonality
of the mode shapes of free-vibration with respect to the mass and stiffness matrices also applies to the damping
matrix it is possible to specify the desired damping levels at two frequencies. If the required fractional of critical
5
i j i j
damping is 8 and 8 at modes i and j with natural circular frequencies T and T respectively then
and
n
The result of this assumption is that at any other mode with natural circular frequency T the fraction of critical
damping is given by
This relationship between damping and natural frequency of free vibration is shown in Figure 1 where it is seen
that as the natural frequency increases the amount of damping increases almost linearly with frequency. The
major popularity of the Proportional damping model is that it uses the mass and stiffness matrices of the structure
and which are already computed within the analysis. Furthermore, the skyline or shape of the damping matrix
is identical with that of the stiffness matrix, and with that of a consistent mass matrix, and therefore does not
increase the size of matrices used in the dynamic analysis and does not affect the computational effort at each
time-step.
Another consideration required in setting up the analysis is whether to use the initial elastic stiffness matrix, the
current tangent stiffness matrix or a combination of both of them.
In the early analyses by Sharpe [Sharpe, 1974] a tangent stiffness matrix was used as this is the current stiffness
matrix at any time step and is available whereas the initial stiffness matrix would have had to retained as an extra
matrix carried right through the analysis. There were objections to the use of the tangent stiffness by the thesis
examiners on the grounds that as the structure became inelastic and the stiffness reduced so did the damping
matrix which did not seem reasonable. The program was then modified to use either the initial elastic stiffness
or the current tangent stiffness with the former becoming the norm for our analyses in the following years.
If the damping remains constant as the structure yields resulting in a decrease in the stiffness, and the natural
frequencies, then the fractions of critical damping in the structure increase. Although extra damping is expected
this is modelled by the member hysteresis and should not be effected twice by an increase in the viscous
damping as well. The effect of increasing the fractions of critical damping as the stiffness reduces may be partially
offset by using the tangent stiffness matrix instead of the initial stiffness damping. In this case the damping matrix
reduces at the same time as the stiffness reduces.
A variant of the Rayleigh damping model is the mass proportional damping model where $ is set to zero. If the
mass matrix is diagonal, which is a very common assumption, then the damping matrix is also diagonal
simplifying the analysis. The consequence is that the fraction of critical damping is inversely proportional to the
frequency which implies very small amounts of damping in the higher modes of free-vibration and which does
not appear to be very realistic.
6
Figure 2 Linear or Tri-linear Damping Model
4.2 Caughey Damping

A means of matching the required amount of damping at a greater number of modes is provided by a damping
model proposed by Caughey [Caughey 1960] where the damping matrix may be expressed as
where q = any integer
N = number of nodes at which damping is specified.
This equation enables the fraction of critical damping 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
b
a and the computationally awkward matrix products involved. Wilson and Penzien [Wilson and Penzien 1972]
proposed a much simpler way of obtaining the same damping model using the N mode shapes of free-vibration.
The disadvantage of this approach is the large eigenvalue problem to be solved for all N natural frequencies and
mode shapes of free vibration before commencing the time-history analysis as well as the other disadvantage
of the Caughey damping model in that the damping matrix C is fully populated, i.e. it is no longer a banded matrix.
This latter effect increases greatly the memory requirements of the analysis as well as the computational effort
at each time-step.
The method suggested by Wilson and Penzien makes use of the properties of orthogonality of the mode shapes
i
with respect to the mass, damping and stiffness matrices. Given the ith mode shape of free-vibration N such that
i
where m is the generalised mass for the ith mode. In a similar manner the generalised damping can be
computed from
If the fraction of critical damping 8 is specified for each mode then the damping matrix C can be obtained using
the inverse of the modal matrix to transform back from the generalised damping matrix. The actual operation may
be simplified and the reader is referred to the original paper of Wilson and Penzien for further details.
In RUAUMOKO there are incorporated three different versions of this damping model. The first assumes a linear
variation of the fraction of critical damping with frequency where the user specifies the damping required at any
two modes. If the same fraction of critical damping is specified at both modes then constant damping is provided
at all frequencies. The second version assumes that the damping is constant at frequencies below the first
7
Figure 3 User Specified Modal Damping
nominated mode with a linear variation of the fraction of critical damping to the fraction of critical damping
specified at the second specified mode and then remains constant to the highest frequency mode in the structure.
A third model, similar to the second, but having linear interpolations used between up to 9 intermediate modes
nominated in between the first and last specified modes.
The second tri-linear model was used by Crisp [Crisp, 1980] who analysed a 6 storey frame where the damping
was specified at mode 1 and the highest mode in the structure to show that the problem of joint equilibrium was
in high damping associated with the high modes. Initially damping in the highest mode was set to that of the Initial
stiffness Rayleigh damping model with 5% of critical damping in modes 1 and 2 to give similar results. Then the
damping in this highest mode was progressively reduced over a series of analyses to a uniform damping across
all modes. The displacements of the structure increased progressively to the case where they virtually matched
those of the tangent stiffness Rayleigh damping model with 5% damping at modes 1 and 5. Since that time we
have generally recommended that Rayleigh damping be specified at mode 1 and at a mode number equal to,
or a little less than, the number of storeys in the frame.
These latter three damping models result in a fully populated damping matrix with a large increase in memory
requirements and computational effort. In the first stage all natural frequencies and their associated mode shapes
of free vibration have to be computed to generate the damping matrix. If, with structures that have a very large
frequency spectrum, some of the highest frequencies are complex because of numerical difficulties in separating
the high mode frequencies, these modes are assumed undamped. In the time-history analysis, the coefficients
of the damping matrix within the skyline of the stiffness matrix are kept on the left hand side of the equations of
dynamic equilibrium while the remaining coefficients operate in a predictor-corrector iteration process within each
time step. This iteration is controlled by the parameters MAXCIT and FTEST, which should be set to 1 or 2 and
0.010 or 0.001 respectively. Further details may be found in [Crisp 1980]. In all the analyses carried out to date
only one iteration was required at each time-step to achieve the desired accuracy.
The program besides having the above damping models and the Rayleigh damping models using either the initial
or tangent stiffness matrix has a further option where different " and $ may be specified for each member in the
structure. This not meant to imply great generality but to enable different structures, say, in carrying out a
pounding study between a steel frame and a reinforced concrete frame to have different levels of damping in
each frame. It may also be used in foundation-structure interaction studies where different levels of damping may
be expected in the structure and in the foundation model. The appropriate " and $ values would be computed
by analysing the individual structures, specifying the damping required at the two modes specified using the
Rayleigh damping model and then using the computed " and $ as part of the section properties for the members
in the different structures etc. (See figures 4 and 5.)
8
RUAUMOKO also has specific translational and rotational DAMPING members or dashpots which may have
linear or non-linear force-velocity relationships. The properties may also differ in the positive and negative
directions. The dashpots may have a displacement gap where the damping coefficient is zero. These members
are designed to represent special damping devices inserted in the structure and where the properties have been
evaluated from laboratory experiments.
Damping is also associated with CONTACT members but only acts whilst the contact members are actually in
contact. Damping can also associated with the GROUND or foundation members. The Elastomeric Damper
hysteresis rule also has velocity dependant damping forces associated with the elastic forces and stiffness of the
member.
Note that the damping only affects the structure during the time-history analysis and has no effect on the static
analysis or on the frequency and mode shape analysis..
9
Figure 4 Different Damping in Different Parts of Model
Figure 5 Different Damping in Different Structures
10
4.3 Effects of Different Damping Models

The majority of non-linear dynamic engineering software allows only the use of the Rayleigh or Proportional
damping matrices and in a large number of the cases this is specified in terms of the coefficients " and $ and
the choice of the use of the initial and tangential stiffness matrices. In some cases separate values of $ may
be specified for a combination of the initial and tangential stiffness matrices. To get the coefficients so that a
required level or fraction of critical damping is attained the modal properties i.e. the natural frequencies of free-
vibration will often have to be estimated in some external procedure. In many cases the damping model is
given scant consideration as there is the belief that as the damping forces are small and that as a correct level
of damping has been specified then no further consideration is required.
In an elastic analysis of a N storey framed structure subjected to a lateral earthquake excitation only the first
N sway modes have any significant contribution to the response and the higher modes associated with local
joint rotations etc. will have a negligible contribution to the response.
As a result of nearly three decades of dynamic analyses of framed structures we have found that the mass
representation of the frame has a considerable effect on the response of the members when inelastic
behaviour takes place and the usual models include associating mass with all joints in the frame including
some mass associated with the rotational degrees of freedom. This latter feature is most important if the frame
members are modelled with elasto-plastic moment-curvature relationships. The horizontal degrees of freedom
in a floor may be slaved together, except in pounding studies where it has been found that the axial
deformation of the floor girders is important when estimating the magnitude of the contact or impact forces.
The problem with such mass models of the structure is that the number of independent dynamic degrees of
freedom increases considerably. With the increase in the fractions of critical damping with increasing
frequency associated with the Rayleigh damping model this means that although the lower modes of free-
vibration may have of the order of say 5% of critical damping it is very easy to get very large levels of damping
in the higher modes where the natural circular frequencies may be of the order of several thousand radians
per second.
When elastic structures are subjected to earthquake excitation only the lateral sway modes of the structure
are excited by the ground motion. As these modes have low natural frequencies, in an N storey frame the Nth
sway mode frequency is approximately (2N-1) times the fundamental mode frequency, the highest mode
contributing significantly to the response is still lowly damped. Even when relatively low levels of inelastic
behaviour are observed in the frame and the higher modes are being excited their contributions are still small
and the small modal velocities only result in small damping forces and moments. However, when the frame
is subjected to strong ground motions, large member in-elastic rotations occur at the member ends. These
rotations are now relatively large joint rotations with respect to the lateral joint displacements (see Figure 7).
If the equal displacement principles are correct then such displacements would normally be associated with
the much smaller rotations that are observed in the longer period sway modes of the frame. The extra
rotations can be considered as being supplied by the higher frequency joint rotation modes. Unfortunately ,
as a result of the Rayleigh damping model, these higher frequency modes have relatively high damping ratios
associated with them. The large higher mode velocities which are only observed as inelastic behaviour occurs
result in large damping forces and moments at the joints of the frame. These damping forces affect the
equations of dynamic equilibrium thereby affecting the displacements of the structure as well as the in-elastic
displacements of the members in the frame.
To illustrate these effects [Carr, 1997] a 12 storey, 2 bay frame (see Figure 6) is subjected to the Pacoima
Dam excitation recorded during the San Fernando earthquake in California in 1971. This earthquake provides
much greater accelerations than are expected for a design earthquake implied in the New Zealand Loadings
Code [NZ4203,1992] but this record has been used as an example of a maximum credible event in order to
evaluate the ultimate response of structures designed to the normal 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 frame have mass associated with them and as all the horizontal degrees of freedom at a level are coupled
the frame has a total of 84 degrees of freedom. An elasto-plastic hysteresis rule is used for all beam members
and the ground floor columns. Following capacity design principles, the upper columns are designed to remain
elastic.
11
Figure 6 12 Storey Frame
Figure 7 Typical Frame Deformations
12
This frame has mass at all nodes, including rotational inertias. The horizontal displacements at all nodes on a
floor are slaved so that there are seven degrees of freedom at each floor, one horizontal displacement, three
vertical displacements and three rotations. This means that there are 84 dynamic degrees of freedom in the 12
storey frame.
Seven different damping models were used
1 Rayleigh damping using the initial, or elastic stiffness matrix and with 5% critical damping in modes 1 and
2. As a result of the damping model mode 84 has 161% of critical damping.
2 As above but 5% critical damping in modes 1 and 10. Mode 84 now has 36% of critical damping.
3. As for model 1 above but using a tangent stiffness Rayleigh damping assuming a tangent damping
matrix is used.
4. As for model 2 above but using a tangent stiffness Rayleigh damping assuming a tangent damping
matrix is used..
5. As for model 1 above but using a tangent stiffness Rayleigh damping assuming a secant damping matrix
is used.
6. As for model 2 above but using a tangent stiffness Rayleigh damping assuming a secant damping matrix
is used.
7. Using the method suggested by Wilson and Penzien with a constant level of 5% of critical damping in
all modes of free-vibration
It must be stressed that in all of these analyses the only difference in the data is in the damping models. In all
cases 5% critical damping has been specified. It will be noted that in cases A and C above the damping in modes
2 and 3 drops to the order of 2.5% of critical damping. For models 1, 2 and 7 above the damping matrix is
constant i.e. the initial (elastic), tangent and secant matrices are the same.
The earthquake chosen for the example is the Pacoima Dam recording taken during the 1971 San Fernando
earthquake. This accelerogram is shown in Figure 8 and the displacement response spectra for the excitation
is shown in Figure 9 where for the fundamental natural period of free-vibration of 1.95 seconds, assuming 5%
viscous damping, the roof displacement is expected to be of the order of 0.5m. This might be compared to the
0.2m displacement expected for such a building in Wellington city, the capital of New Zealand. This means that
the Pacoima Dam acceleration record is stronger than a design level earthquake for Wellington.
Figure 10 shows the differences in the roof displacement when the frame is subjected to the Pacoima Dam
excitation. The commonly used initial stiffness Rayleigh damping where the " and $ are computed from damping
specified at the first and second modes of free vibration, shows smaller responses. Which response do you
want?
It can be seen that the displacements are markedly affected by the choice of damping model. Similar effects also
show in the displacements at the mid-height of the frame. The base shears of the frames are similar in all of the
analyses but there are significant differences in the ductility requirements of the girders in the frame.
Figure 11 shows the different damping moments generated at the central joint at the level above the ground floor.
The general assumption that the damping forces are small is not obvious in all these analyses. In the case of
initial stiffness Rayleigh damping where the 5% of critical damping is specified in modes 1 and 2 damping
moments of 500 kNm, almost half the yield moment in the adjoining girders, are shown. The tangent stiffness
Rayleigh damping models and the constant damping model show quite small damping moments. It will be seen
that the large damping moments 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 damping forces acting at level 1 of the frame for the three of the damping model. The usual
assumption by engineers is that the damping forces are small in comparison with the other forces acting in the
structure. For a single degree of freedom structure with 5% of viscous damping the damping 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 damping
coefficient is help constant then the damping force may 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 mass times 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 Damping using the initial stiffness matrices
the damping forces are at times quite large compared with what is expected. This is not so when constant, or
uniform, damping is applied to all modes. It must be noted that is the amount of inelastic behaviour is small then
the differences seen in the results for the different damping models are also small.
The different analyses also show significant differences in the total acceleration records produced at the roof level
and the roof acceleration spectra show almost a 50% variation in the short period responses.
13
In order to show that the results are not strongly dependant on the choice of hysteresis model the analyses were
repeated for the case where the Clough degrading model was used for all inelastic action in the beams or girders.
Although the time-history plots show a different response, the peak displacements for all damping models are
almost identical to those with the elasto-plastic hysteresis. The damping moments show similar magnitudes to
those for the elasto-plastic models but there is a greater number of large damping moment spikes.
In the work done by Crisp [Crisp 1980] on a 42 degree of freedom 6 storey frame the linear and tri-linear damping
models increased the computational effort required for the analyses by approximately 50%. In these earlier
analyses the structure stiffness matrix was in the form of a constant bandwidth matrix and not the skyline
equation solver used in the current version of RUAUMOKO with its optimised equation numbering. There is an
increase in computational effort because of the necessity to carry out the eigenvalue analysis to get all the mode
shapes and frequencies of free-vibration and because the resultant damping matrix is fully populated. In
RUAUMOKO the computational effects of this are reduced by leaving only those terms within the skyline of the
stiffness matrix on the left-hand side of the equations of incremental equilibrium and putting the off-band terms
on the right-hand side and solving by iteration. It has never required more than one iteration to get a satisfactory
solution. However as the number of degrees of freedom increase the number of coefficients in the off-band part
of the matrix increases involving greater computational effort. Using a modern unix workstation with real-time
graphics, or current Microsoft Windows operating systems there is no appreciable difference in the times
required for the analysis cases 1 through 7. If the graphics is suppressed then the computational times are
reduced by about 45% with case 7 taking about 12% more time than case 1. This means that there is now little
significant penalty in using the damping matrices proposed by Wilson and Penzien. The only difficulty is that, at
the moment, these are based on the initial stiffness matrix which means that the effective damping ratios will rise
above 5% when the structure yields.
It has been found that if one uses the damping matrix proposed by Wilson and Penzien then degrees of freedom
without mass are also undamped. This follows from the equation of free-vibration.
where refer to the parts of the mode shape associated to degrees of freedom with and without mass
respectively.
It is obvious that the elastic forces associated with the mode shape must be self-equilibrating at the non-massed
degrees of freedom as no external forces can be present. This effect results in the damping forces associated
with the mode shape being zero at those degrees of freedom without mass.
There is another consideration that must be considered when using a tangent stiffness damping model and that
is the way that the damping acts in the structure. When the Rayleigh tangent stiffness damping model is applied
to the incremental equations of equilibrium as part of the Newmark integration method the damping matrix using
the Rayleigh damping matrix is the tangent damping matrix.
In the equations of incremental equilibrium as set out for the Newmark integration schemes (see the text by
Clough and Penzien or that by Chopra) the mass, damping and stiffness matrices required are all tangent
matrices. These give the increment of inertia, damping or elastic forces due to the increments of acceleration,
velocity and displacement. Most dynamic analysis programs still use the incremental equilibrium equations in
their implementation of Newmarks methods of time-step analysis. In nearly all cases the changes in the mass
matrix are assumed to be insignificant or inconsequential and the mass matrix is help to be constant throughout
the analysis. All the dynamic time-history programs use the tangent stiffness matrix which will change every time
step where the properties of the members change. In all the early dynamic analyses the damping matrix was
based on the elastic stiffness matrix, was therefore a constant matrix so that the elastic, tangent and secant
matrices are the same. The problem of using the initial stiffness is that as the natural frequencies of the structure
reduce as cracking or yield takes place, the damping coefficient remain constant implying that the fractions of
critical damping increase. The idea of using the tangent stiffness matrix to form the damping matrix partially
compensates for this by reducing the damping coefficients partially in line with the reduction of the natural
frequencies of free-vibration
14
In the mid-1980s Ruaumoko was changed from using the equations of incremental equilibrium to using, at each
time-step, the equations of equilibrium at the end of the time step. The forces art the end of the time-step are
those at the beginning of the time-step plus the tangent mass, damping and stiffness matrices multiplied by the
increment in acceleration, velocity and displacement respectively. This result is that the inertia forces, damping
forces and elastic forces are computed at every time step to ensure dynamic equilibrium is enforced. If the
damping matrix is constant the damping forces may be obtained by the incremental summation described above
or by multiplying the current velocities by the damping matrix. If the tangent damping matrix model is applied then
the incremental method, the damping forces at the end of the step are the damping forces at the beginning of
the step plus the increment caused by the tangent damping matrix multiplied by the increment in the velocities.
The problem noted where the tangent damping matrix is derived from the tangent stiffness matrices is that if the
structure exhibits hysteresis then so does the damping. This means that when the velocity of the structure goes
to zero at the end of the earthquake the damping forces do not go to zero but one is left with residual due to the
permanent plastic deformations in the members.
In the early versions of Ruaumoko the damping forces at each time step were computed using the damping matrix
as a secant matrix. It was also used as the tangent matrix in the incremental equations of equilibrium. When this
mis-interpretation was corrected in 2002 so that the matrix was used strictly as a tangent damping matrix there
was an outcry from some users who found that their results were different from those obtained earlier.
Another interpretation is that the current damping forces are the product of the Rayleigh damping matrix, using
the tangent stiffness matrices, times the current velocity vector. This implies that the damping matrix is being
interpreted as a secant damping matrix. In this case there are difficulties in defining the tangent damping matrix
to use in the equation of incremental equilibrium. New options have been added to the program to allow the user
to use the Rayleigh tangent stiffness damping as either a tangent damping model (the default tangent damping
model) or as a secant damping model which was then way the damping was set up in Ruaumoko prior to 2002.
If the initial stiffness Rayleigh damping model is used or the Wilson-Penzien damping models are used then the
damping is constant and there are no differences between the initial, tangent or secant damping matrices
4.4 Recommendation
It is recommended that where practical, or until better information is available, a uniform damping should be
specified in all modes. This is ICTYPE = 2 with the fraction of critical damping specified at the two modes be the
same.
If a Rayleigh or Proportional damping model is used where the frequencies at which damping is specified are such
that the highest modes of free vibration are at least sub-critically damped.
It would also appear reasonable that the tangent stiffness matrix is a better choice than the initial elastic stiffness
as with a non-changing damping as the structures reduces its stiffness as inelastic effects takes place implies that
the fractions of critical damping increase as the natural period lengthens. However, as discussed above, the
tangent damping matrix model using the tangent stiffness matrix that when the stiffness matrix exhibits hysteresis
then so does the tangent damping matrix. This implies that when the velocities go to zero the damping forces
may be non-zero. For this reason it is suggested that the tangent stiffness matrices be used to contribute to a
Secant damping matrix i.e. ICTYPE = 6. (This was what ICTYPE = 1 implied until 2002)
15
Figure 8. Pacoima Dam Accelerogram (1971 San Fernado Earthquake)
Figure 9. Displacement Response Spectra for the Pacoima Dam Accelerogram
16
Figure10. Displacements at the roof of the 12 storey due to the Pacoima Dam Accelerogram
Figure 11. Damping Moments at Central Joint Level 1
17
Figure 12. Horizontal Damping Forces at Level 1
Figure 13. Relative Horizontal Inertia Forces at Level 1
18
Figure 15 Rigid End-blocks
5. STRUCTURAL MEMBERS
The program has different member models to represent the stiffness of the structure. These fall into
several categories, Frame, Spring, Dashpot, Tendon, Contact, Quadrilateral, Masonry Panel and Ground
or Foundation members. The two-dimensional program also has a reinforced concrete wall member.
Figure 14 Frame Member
5.1 Frame Members
The Frame member type covers the beam and beam-column members. A beam member is a general three
dimensional member which may use almost any of the hysteresis rules governing the behaviour of the plastic
hinges that may form at each end of the member. A beam member may also have a bi-linear axial load - axial
displacement hysteresis. However, there is no interaction between the axial yield states and those associated
with the moment-curvature yield states. A beam-column member differs from a beam member in that the axial
force in the member affects the current yield moments at each end or the member. There are three axial load -
bending moment interactions built into the program, one for reinforced concrete columns, one for steel
columns and one for a more general column. In the two-dimensional 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-column member, in general, follows the concept of the Giberson
one-component model [Sharpe, 1974] which has a plastic hinge possible at one or both ends of the elastic
central length of the member.
Rigid end-blocks may be incorporated within the length of any of the Frame members. If there are joint
flexibilities or shear deformations, the member stiffness is inverted to get the member flexibility, the joint and
shear flexibilities are added and the resulting matrix is again inverted to get the final stiffness of the beam
member.
19
Figure 16 Giberson One Component Beam Model
Figure 17 Giberson Hinge Model
The stiffness of the hinge is controlled by the tangent stiffness of the current point on the appropriate hysteresis
rule.
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 same 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 moment-curvature relationship is M = f EI N where f < 1 is
20
Figure 19 Variable Flexibility Beam Model
Figure 18 Two Component Beam Model
An alternative beam member is the two-component beam [Kanaan 1973] where two members in parallel
represent the behaviour of the member. One member is elastic and the second is elastic or has a perfect hinge
at one or both ends of the member. Traditionally, this member could only represent a bi-linear hysteresis rule
but the member formulation has been generalised so that it can follow most hysteresis rules.
Another beam member is one in which the inelastic behaviour is spread along the member hinge length. The
yielding zone has a flexibility which varies parabolically from the inner elastic zone to a maximum flexibility at
the member ends. This member cannot be used to model perfectly plastic behaviour as the flexibility becomes
infinite at the ends of the member.
A final form of frame member available only in the two-dimensional program is the Four-Hinge beam member
which can allow for two plastic hinges within the span of the member in addition to the two hinges at its ends.
The two outer sub-members are Giberson one-component beams and the inner sub-member is a fully elastic
beam. The beam may be used to model gravity dominated beams where under seismic 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 may also be used to represent a haunched member with the hinges forming at the interior
ends of the haunches. This is achieved by giving the inner beam a fraction of the outer component stiffnesses
and by making the end hinges very strong or by setting both end yield moments to zero (default elastic
behaviour). If shear deformations are specified it is assumed that both the shear area and moment of inertia
of the central section have the same stiffness reduction factor when compared with the two end sections. If
the frame member is linear elastic then all the different beam and beam-column members are identical in their
behaviour.

Figure 20. 4 Hinge Beam
21
Figure 21. Spring Member
5.2 Spring Members
Spring members may be used to model special effects in the structure. In two-dimensional structural analyses
they can be used to represent members acting out of the plane of a frame but representing forces that act in
the plane of the frame. An example of the latter is a rotational spring representing the torsional behaviour of
a beam oriented perpendicular to the plane of the frame and connecting it to an adjacent parallel frame. The
spring member orientation is given by the axial orientation of the member but if the two end nodes coincide
resulting in a zero length member then the longitudinal and transverse directions coincide with the structure,
or global, X, Y and Z axes respectively. In the two-dimensional 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 dimensional program the spring member may have a longitudinal spring, two transverse springs,
a torsional spring and two rotational springs. In the two-dimensional 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 displacements of the two ends. The rotational spring
moments are only proportional to the differences in the rotations at each end of the member. If the end nodes
are coincident then the transverse rotational components behave like the torsional clock spring. This member
may be thought of as a generalised Truss member which may 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 member behaviour is represented by a three-component spring and therefore follows a tri-
linear hysteresis rule. The longitudinal and rotational components follow a bi-linear hysteresis. In two-
dimensional analyses this may be used when modelling a bridge pier when the plane of the analysis is that of
the bridge deck.
A third variant is similar to the first spring member except that the transverse or shear behaviour follows a
modified SINA hysteresis rule and the yield forces in the transverse direction are also a function of the
associated rotational spring ductility. This member is designed to model beam-end hinges where there is
possibility of a shear failure following yield in flexure. This is particularly useful in modelling frames designed
to earlier building codes where capacity design philosophies were not in use.
22
Figure 22. Damping or Dash-pot Members
Figure 23. Tendon Member
5.3 Damping or Dash-pot Members
Damping members may be used in the structure to represent the actions of local viscous energy dissipaters
that may exist in the structure. The damping member is similar to an elastic spring member in that it has up
to six damping actions, a displacement action in the longitudinal direction and the two transverse directions
and three rotational actions. These members are only used in the time-history analysis and contribute to the
damping matrix of the structure. If the member length is zero the longitudinal and transverse directions coincide
with the structures global X, Y and Z axes. The member has been extended to allow for a non-linear force-
velocity relationship. In the two-dimensional program the four nodes I, J, K and L lie in the global X-Y plane
and node M is not used and the damper actions are similar to the two-dimensional spring member.
5.4 Constant-Force and Active-Tendon Members
These members have no stiffness properties but are used to apply forces to the structure. In the Constant-
Force members the forces acting on the joints at each end of the member are a function of the displacements
between the joints and the direction of the change in the member deformation. The member is like a truss
member in that it carries only an axial force. If the member is of zero length the member local x axis is in the
direction of the global X axis. In the two-dimensional 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 member is similar to the Constant-Force member but the force is a function of the
displacements, velocities or accelerations of specified nodes in the structure. There is provision to apply a
time-delay in the response of the tendon. These members may be used to model simple active control systems
in the structure.
23
Figure 24 Contact Members
5.5 Contact Members
These members were incorporated in RUAUMOKO to represent the behaviour of members that model pounding
between buildings during earthquakes as well as a foundation-soil rocking interaction. The member has both
stiffness and damping actions where the damping coefficient is a function of the current stiffness of the contact
member. There is also provision to apply friction forces in the directions perpendicular to that of the contact
member axis. If the member is of zero length the contact is assumed to act in the global X axis direction. In the
two-dimensional 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.
24
Figure 25 Quadrilateral Finite Elements
5.6 Quadrilateral Finite Elements
A Hybrid Stress Type II quadrilateral finite element has been incorporated into the program to allow for the
modelling of in-fill panels and to allow for foundation modelling, particularly if coupling effects between adjacent
foundations is required. The element assumes a cubic variation of the x, y and shear stresses over the element.
The element edges have a cubic variation of normal displacement and a linear variation of the tangential
displacement along each edge. This means that the edge displacements are compatible with any adjacent beam
members. A nine point Gaussian quadrature is used to form the element stiffness and a three point Gaussian
integration is used along each element edge. This member is, at present, only linearly elastic. Either plane stress
or plane strain material models may be selected.
This element also has available a plate-bending action, also based on a Hybrid-Stress formulation so that plates
or shells may be modelled. The element may be used to model walls or floor slabs in a framed structure.
All four nodal points must be distinct, i.e. triangles are not permitted. The nodal points must be numbered in an
anti-clockwise sequence around the element. The direction determines the direction of the local z axis and hence
the sign of the stresses and bending moments in the element.
In the two-dimensional 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 element properties.
25
Figure 26 Truss Mechanism
5.7 Masonry Panel Elements
The four-node masonry panel elements proposed by Crisafulli [Crisafulli, 1997] are designed to represent the
behaviour of masonry in-fill panels which are surrounded by reinforced concrete or steel frame members. Each
panel is represented by five strut members, 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 compression and so connects different top and bottom corners
depending ion the deformation of the panel. The first four struts use the masonry 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 compression forces carried across
the diagonal of the panel.
An elastic plate bending action may also be considered as part of the stiffness in this element. The element is
assumed to be near rectangular in shape and that the local or element y axis is meant to be in the vertically
upward direction.
All four nodal points must be distinct, i.e. triangles are not permitted. The nodal points must be numbered in an
anti-clockwise sequence around the element.
In the two-dimensional program node I, J, K and L lie in the global X-Y plane.
26
Figure 27 Foundation or Ground Elements
5.8 Foundation or Ground Elements
These elements developed by Chambers [Chambers 1998] and extended by Rahman [Rahman 1998] are beam-
like members designed to represent simple soil-structure interaction effects. These members may be thought
of as a distributed Winkler spring model. There are several different representations of the stiffness, damping
and mass properties of the element. At the present time these members have only stiffness in the local x-y plane.
In the two-dimensional 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.
27
Figure 28 Structural Wall Member
5.9 Structural-Wall Members (Two-dimensional Ruaumoko-2D only)
The structural-wall member was developed as the Taylor Wall-A element [Taylor 1977] to represent the
behaviour of reinforced concrete walls. The member cross-sectional area and second moment of area are
numerically integrated across the wall section using the current steel and concrete modulii. As a result the model
allows for the shift of the neutral axis position due to the changing axial load and bending moment. The initial
position of the neutral axis is assumed to be that obtained from the uncracked section. The member is
computationally expensive in that smaller than normal time-steps and Newton-Raphson iteration at every time
step is usually required to maintain satisfactory equilibrium. Taylor also often used several elements to represent
a single storey. As a result, for most analyses, structural-walls have been represented by beam-column
members with shear deformations included.
The integration of the stiffness along the member length is accomplished using a Lobatto integration instead of
the original Simpson's Rule integration. The number of sections may be specified from 3 to 7. The properties of
each section is evaluated by assessing the stresses and stiffnesses of a number of segments across the section.
The number of segments, or filaments, must be between 3 and 20. As the sections are assumed to be initially
uncracked the stiffness of the member may be unrepresentative of the actual section because some cracking
will be present due to shrinkage or earlier excitations. To allow for these reductions of stiffness, a factor to limit
the maximum fraction of the initial flexural stiffness is provided. This factor will enable the natural frequencies
of free-vibration of the initial structure to take more realistic values than those associated with the uncracked
structure.
The original Taylor element used a very simple 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 more 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 model uses a Bounded Surface rule [Zhu 1995] for the steel. This is a simpler
rule than the Ramberg-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 member designated by having only 2 sections to represent a Giberson like
beam-column with Taylor wall-type hinge sections at each end and an elastic region between them.
28
Figure 29 Five Node Member
5.10 Five Node Definition of One Dimensional and Two Dimensional Members
All members except the quadrilateral finite elements and the masonry panel elements are defined by five nodal
points. The two outer nodes are the usual nodes where the member forces and stiffnesses act and the inner two
nodes are used to define rigid links connecting the deformable part of the member to the outer nodes. If the
inner nodes are not defined, or are zero, they are taken as the same as the outer nodes and there are no rigid
links. The aim of this definition is to enable modelling of complex structural geometries without having to resort
to artificial very stiff members to arrange the interconnection of members. These artificial very stiff members run
the risk of destroying the accuracy of the total stiffness matrix besides markedly increasing the size of the total
stiffness matrix. If artificial members are used the interior nodes have their own degrees of freedom, increasing
the total number of degrees of freedom and the artificial members, often with stiffnesses many orders of
magnitude greater than those of the deformable members in the structure, control the significance of the
stiffnesses in a computer system carrying only a limited number of significant digits. With the five-node definition
the inner nodes do not have any degrees of freedom and the displacements of the inner nodes are rigidly linked
to the displacements 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 major principal z axis of the member. The local axes have their
origin at node K; the local x axis lies along the member, the local z axis lies on the plane of nodes K, L and M
and is perpendicular to the axis of the member and lies on the same 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 elements differ in having only
four nodal points, i.e. node M is zero.
In the two-dimensional 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-dimensional analyses.
29
Figure 30. Quadrilateral Finite Element
The quadrilateral elements and the masonry panel element are four node elements (triangles are not permitted)
and the four nodes must be in an anti-clockwise (counter-clockwise) sequence around the element. The masonry
panel elements are presumed 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 matrix is stored as a column-stored sky-line matrix. As the matrix is symmetric only the
diagonal and above diagonal terms are stored. During the time-history analysis the matrix is updated with the
changes in the member stiffness matrices. The member data-base for each member retains a copy of the latest
member tangent stiffness matrix. The equations are automatically renumbered using an algorithm by Sloan to
optimise 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 Wilson and
Dovey [Wilson 1978]. If necessary Newton Raphson iteration may be used at each time-step to eliminate residual
forces resulting from the change in member stiffnesses during the time-step. This iteration is controlled by the
parameters MAXIT and FTEST. If MAXIT = 0 then no iteration is allowed. MAXIT would normally be set to the
order of 5 cycles if iteration is enabled. FTEST represents the ratio of the squares of the norms of the residual
force vector and the incremental force vector at the time step. FTEST = 0.01 implies a 10% average error and
FTEST = 0.001 implies a 3% average error. Any residual force vector remaining at the end of the iteration is
added to the next increment of force vector in an implied self-correcting procedure.
Statistics on the numbers of iterations performed and the number of times the stiffness matrix of the structure
is updated during the time history is provided at the end of the output file. If the structure is non-linear while
computing the solution to the static loads, a maximum of 5 cycles of Newton Raphson iteration is carried out.
The number of iterations required is output with the static solution.
30
Figure 31 Elasto-plastic and Bi-linear Hysteresis Rules
Figure 32. Ramberg-Osgood Hysteresis Rule
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
Frame and Spring members. They range from the simple elasto-plastic and bi-linear rules, the computationally
more expensive Ramberg-Osgood rule [Sharpe 1974] to rules such as those developed by Wayne Stewart
[Stewart 1987] which requires over thirty parameters to keep track of the current stiffness.
31
Figure 33. Bi-linear with Slackness Hysteresis Rule
Figure 34 Kivell Pinching Hysteresis Rule
The bi-linear with slackness model shown in Figure 28 can be used to represent diagonal braced systems where
yield in one direction may stretch the members leading to a slackness in the bracing system. The pinching model
of Kivell [Kivell 1981] shown in Figure 29 was designed to represent the behaviour of the nails in steel nail-plate
units connecting timber members together at the joints.
The majority of the degrading rules have been developed to represent the behaviour of reinforced concrete
members. The simplest rule is the Clough Degrading Stiffness which may be regarded as a sub-set of the
Modified Takeda hysteresis rule [Otani 1974]. Examples of these rules are shown in Figure 30 to 36.
32
Figure 35. Modified Takeda Degrading Stiffness Hysteresis Rule
Figure 36. Origin Centred Stiffness Hysteresis Rule
Figure 37. SINA Degrading Stiffness Hysteresis Rule
33
Figure 39. Mutos Degrading Stiffness Hysteresis Rule
Figure 40. Fukada Hysteresis Rule
Figure 38. Degrading Bi-linear Hysteresis Rule
34
Figure 41. Mehran Keshavarzians Degrading Hysteresis Rule
Figure 42. Li Xinrong Reinforced Concrete Column Hysteresis Rule
Li Xinrong [Li Xinrong 1995] has developed a model which allows for the changes in the stiffness of reinforced
concrete columns as the axial force in the column changes. This is shown in Figure 37.
35
Figure 44. Non-linear Elastic Rule
Figure 43. Wayne Stewarts Degrading Stiffness Hysteresis Rule
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].
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.
36
Figure 45 Hertzian Contact Spring
Figure 46 Bouc Hysteresis Rule
Figure 47. Ring-Spring Hysteresis
The Hertzian Contact rule [Davis 1992] shown in Figure 45 is useful for modelling the contact between
impacting structures.
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].
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.
37
Figure 48 Degrading Strength Rule
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.
This has been extended recently to allow for a tri-linear degradation of strength with ductility or cycle number.
It must 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 assumed to be elastic. This means 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 member would suddenly act as an elastic member.
A 1% strength is close enough to zero for engineering purposes.
38
7 APPLIED LOADS
7.1 Static Loads.
Static loads may be input as nodal loads and/or as member loads. If Frame members are loaded then the
member loads, covered as part of the section data, should be applied as this will give the correct moments at the
ends of the members ensuring that the yield interaction diagrams are working with the total moment acting in the
members at that point. The nodal loads can also represent the loads coming from the columns and from
members oriented perpendicular to the frame. It must be noted that the applied loads do not contribute to the
mass matrix and that the self-weights do not contribute to the static loads on the structure. The static analysis
is performed before the modal analysis so that the effects of the axial forces acting in the columns can be taken
into account in the modal analysis. The static analysis is the starting point for the dynamic analysis as this
ensures that all members start with the correct force distribution before commencing the time-history analysis.
7.2 Earthquake Ground Acceleration Excitation.
The dynamic excitation is applied in terms of a ground acceleration history applied to all fixed X, Y or Z
displacement degrees of freedom, depending whether a one, two or three component excitation is being applied.
All earthquake accelerograms are assumed to be input in units of the acceleration of gravity. To get the
acceleration value to excite the structure the accelerogram is internally multiplied by the acceleration of gravity.
In the default form of analysis, the displacements, velocities and accelerations are relative displacements, relative
velocities and relative accelerations. Total accelerations, velocities and displacements can be generated by the
post-processing program DYNAPLOT.

If a travelling wave input is being used, the wave delay time at each support node is computed using the
coordinates of the node and the wave velocities in the global directions. The node with the first arrival time is
identified and it is assumed that the motion arrives at this point at time t=0.0. Delay times are then computed for
all other support nodes. At each time step the ground velocities and displacements are integrated from the
ground acceleration records taking into account the appropriate time delays using a linear variation of
acceleration from time-step to time-step in the input record. The displacements, velocities and accelerations
computed by the program are total displacements, velocities and accelerations. Relative accelerations, velocities
and displacements may be obtained using DYNAPLOT. It must noted that many accelerograms do not start from
'at rest' conditions and if the initial velocity, and displacement, are known then they should be input, this will tend
to prevent the displacements of the structure linearly increasing with time 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 time.
7.3 Earthquake Ground Displacement Excitation.
The dynamic excitation is applied in terms of ground displacement histories applied at specified nodal degrees
of freedom. The number of different ground displacement histories depends on user input. The input histories
have the same input formats as the above ground acceleration histories. The displacements used in the
analyses is the same total displacement formulation used in the travelling wave analyses described above.
7.4 Dynamic Force Excitation
Loads may be applied to the structure as one, two or three load patterns each of which is multiplied by its own
load time-history. These time-histories are input using the same formats as are used for the earthquake ground
acceleration records but in this case these time-histories are multipliers of the forces in the load pattern, or load
shape, vector.
7.5 Active-Tendon Loading
Loads may applied to parts of the structure by the Tendon members. In the constant force member the force
in the tendon is a function of the displacement and velocity in the member. In the active tendon member the force
is governed by combinations of the accelerations, velocities and displacements of the structure. A time-delay
may be imposed on the response of the active tendon. This member may be used to model simple active control
mechanisms.
39
7.6 Pushover Analysis
A pushover analysis may be achieved by using the Dynamic Force Excitation using a slow ramp loading function.
The load should be applied slowly enough that inertia forces are insignificant. If the maximum load exceeds the
total capacity of the structure the analysis may become unstable. The mass can be omitted in the pushover
analyses but the inertia may be all that retains analysis stability if the maximum strength is exceeded in the
structure, or at a joint, and an elasto-plastic model is being used.
7.7 Adaptive Pushover
In the normal 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 major difficulty is to assess how much to
increase the load without causing the analysis to fail because the load has exceeded the capacity of the structure.
Another difficulty with the normal pushover analysis is the loading distribution applied to the structure. Many
analysts take the seismic code equivalent static or first mode loading pattern but the difficulty is that the capacity
of the structure is reflected in the loading pattern used and many engineers are not convinced that the seismic
code loading pattern is appropriate for a frame structure in its ultimate state as the forces on a real structure in
an earthquake are functions of the accelerations of the structure and mass 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 assessment of structures built to earlier seismic codes Satyarno
[Satyarno 1998,1999] suggested an adaptive pushover analysis where the loading pattern reflects the
deformation pattern of the structure and where the analysis automatically terminates when the capacity of the
structure is reached. This method has also shown itself to be independent of the initial choice of loading pattern
except that the pattern chosen does influence the number of steps required to reach the structures capacity.
Figure 51 shows the results of the adaptive pushover analysis when compared with the standard pushover
analysis. As shown the final ultimate, using the analysis termination process described later in this section is
independent of the choice of loading pattern. The loading pattern adjusts itself to the deformation of the structure.
The analysis starts by taking the loading pattern described in the SHAPE section of the manual. This is identical
to the starting point for a normal push-over analysis except that instead of this pattern of loading being multiplied
by a time-like function the load pattern is multiplied by the factor " where
where DT and TIME are described in line 3 of the input data. The factor 2 above may be altered by supplying
a number 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 estimate the tangent
fundamental frequency of the structure.
If R is the displacement during the past increment due to incremental forces {g}
ie
where is the current tangent stiffness matrix.
From the equation of free vibration
40
Figure 49. Pushover Loading Patterns
where T is the current tangent fundamental natural frequency and [M] is the mass matrix and {N} is a mode
shape of free vibration.
Let {R} be an estimate of the mode shape.
ie
and
Note:
For the next step
so the new incremental load vector is a function of the mass, the equivalent frequency and the displaced shape
of the structure. The increment is normalized so that the magnitude of the increment of displacement is similar
to that of the first step.
During the pushover analysis damping is ignored and the mass is only used to compute the incremental loads.
The analysis terminates when
(1) T is less than 10 T at the first step
2 -6 2
(2) The Newton Raphson iteration is not achieved within the maximum number of cycles specified
in MAXIT
(3) The stiffness matrices become singular.
(4) The specified maximum structure displacement is reached
As the analysis is now unlikely to reach the duration TIME the post-processor program DYNAPLOT has been
modified to check the actual duration of the post-processor information and to reset the duration used within
DYNAPLOT.
41
Figure 50. Conventional Pushover Results
Figure 51. Adaptive Pushover Versus Conventional Pushover
42
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 displacement history is supplied for a specified displacement degrees
of freedom at a specified node. The load increment is scaled to generate the total nodal displacement in the
history over approximately 90% of the time-steps specified in the input data. The loading history starts the same
way as in the normal adaptive push-over with the loading distribution changing as the structures stiffness
changes. Once the displacement at a peak in the displacement 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 commences and the force
distribution should be similar the forces at the start of the loading with the initial elastic structure.
43
8 MODAL ANALYSIS
The program may carry out a modal analysis even though the results are not generally used during the dynamic
analysis. A modal analysis does provide a check on the structural data in that the user can check that the natural
frequencies and mode shapes are what would be expected for such a structure. In some cases a modal analysis
is necessary as the natural frequencies of free vibration, and in some cases the mode shapes, are used to
generate the appropriate damping matrix for the structure.
Animated representations of the modes shapes may be displayed on the computer screen if desired.
Taking the equation of undamped free vibration, where no loads are assumed to act upon the structure, the N
degree-of-freedom equation of equilibrium becomes
i i i
and assuming simple harmonic motion {u} = {M} Y sinT t then the equation of free-vibration simplifies to
i i
where {M} and T are the ith mode and frequency of free vibration respectively.
i
The N vectors {M} form a Basis set of vectors in that any vector in the N dimensional space may be represented
as a combination of the mode shapes
where {Y} are the modal amplitudes and [M] is the modal matrix in which each column is a mode shape.
Substituting this into the equation of equilibrium and pre-multiplying by [M] gives
T
where
From the properties of orthogonality of the mode shapes it can be shown that [M ], [C ] and [K ] are diagonal
* * *
matrices with
Thus for each mode
The system is now represented as N uncoupled single degree-of-freedom systems.
44
i
Dividing through by M the second order ordinary differential equation is obtained for each mode i as
*
i
The term PF is called the Participation Factor for the ith mode and it is an indicator of how much the ith mode
is excited by the ground acceleration in the direction of the earthquake and indicates the importance of the
contribution of the ith mode to the displacements of the structure. It should be noted that the numerical
magnitude of the Participation Factors depends on the type of normalization used for the mode shapes.
i
Once the Y are found then the relative structural displacements are found from
and the effects of the choice of normalization of the mode shapes is cancelled out.
i
In a modal Response Spectrum analysis the Base Shear V in the ith mode of a structure can be obtained from
A
the Spectral Acceleration S [Carr 1994] using the following equation.
The Effective Weight of the ith mode indicates the importance of the contribution of the ith mode to the total base
shear acting on the structure in the same way that the Participation Factor shows the contribution of the ith mode
to the displacements of the structure. The number of modes required in a modal analysis is specified in many
codes to be such that the sum of the Effective Weights of the modes used must be at least of the order of 90%
of the total weight of the structure.
In RUAUMOKO the modal analysis is normally performed after carrying out the static analysis as this allows, in
P-Delta and large displacement analyses, for the adjustment of the member stiffnesses of frame members that
have axial loads in them. Compressive forces will lead to a geometric stiffness terms that reduce the stiffness
of the members. This means that in multi-storey frames the lateral stiffness of the structure more accurately
represents the real structure with gravity acting upon it.
8.1 Reduction of Eigenvalue Problem for Degrees of Freedom Without Mass
In RUAUMOKO many of the degrees of freedom may not have mass and this requires a static condensation
[Clough and Penzien 1992] process to remove 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
method does not require rearrangement of the stiffness matrix but uses a static analysis approach.
For a standard static condensation
1 2
where {N } are the mode shape associated with degrees of freedom with mass and {N } are the parts of the mode
shape associated with mass-less static degrees of freedom.
From the second equation
Sub
45
stituting into the first equation gives
Once the mode shape and natural frequency are computed the remaining terms in the mode shape
are obtained from
The disadvantage of this approach is that the stiffness matrix of the structure has to be rearranged and although
the computation of can avoid the computation and inversion of what may be a large matrix by using
a backward Gauss-elimination this is still an expensive step [Sharpe 1974].
Using a method used by the author for dynamic analysis of thin shells [Carr 1967] starts by setting up unit load
vectors for each degree of freedom that has mass. By selecting the displacements for each degree of freedom
that has mass from the flexibility vector for each of these load cases a condensed flexibility matrix is computed.
The equation of free vibration can now be written as
The change of variable
and after substituting and then pre-multiplying by (note is a symmetric matrix) leads to the eigenvalue
problem with a symmetric matrix. If is a diagonal matrix this is very easily achieved.
When the eigenvectors have been computed the part of the node shape associated with degrees of freedom
having mass is obtained.
Using this approach has the advantage that the natural frequencies and mode shape are found most
accurately for the lowest natural frequencies rather than for the highest frequencies which occur when the normal
stiffness formulations are used. The eigenvalues are now the squares of the inverse frequencies and not the
squares of the frequencies and it must be noted that most eigenvalue algorithms find the largest eigenvalues with
greatest relative precision. Once the mode shapes for the degrees of freedom having mass are computed the
whole mode shape is computed from the equivalent of
This method has the advantage that the actual degrees of freedom do not need re-arranging and the skyline form
of the stiffness matrix is retained.
46
9 TIME-HISTORY INTEGRATION
9.1 Newmark Constant Average Acceleration Method
The dynamic equation of equilibrium is integrated by the unconditionally stable implicit Newmark Constant
Average Acceleration (Newmark $=0.25) method [Clough 1993]. The time step should be less than 0.1 of the
period of the highest mode of free vibration that contributes significantly to the response of the structure. In
general for multi-storey framed buildings, experience has shown that 0.01 seconds is satisfactory but for most
digitized earthquake accelerograms the time step should never exceed 0.02 seconds. However, the user must
investigate the accuracy of the analyses by checking that using a smaller time-step the results do not change
significantly. The Newmark scheme has been modified from the original incremental equilibrium method to an
equilibrium approach to ensure the maintenance of equilibrium at each time-step. As a further option, the
Newton-Raphson iteration scheme can be employed to converge to a true solution at each time-step. Any
residual force error is carried forward to the next time-step in a self-correcting procedure. The Constant Average
Acceleration method has the advantage of being unconditionally stable but also the advantage that not all
degrees of freedom need to have an associated mass.
During the time step from time t to time t+)t the acceleration is assumed to be constant
Integrating with respect to time over the time-step )t to get the velocity and displacement and rearranging to use
the increment in the displacement )u as the variable gives the increment in the acceleration
and the increment in the velocity as
Substituting into the equation of equilibrium at time t+)t gives
Noting that the stiffness term may be rewritten as
where [K(t)] represents the secant stiffness matrix at time t and the elastic forces are the nodal equivalent of the
T
member forces at time t and the matrix [K ] is the current tangent stiffness matrix.
Similarly the damping term may be rewritten in terms of the nodal damping forces and the current tangent
damping matrix and the increment of the velocities.
T
where the damping forces are those at time t and the matrix [C ] is the current tangent damping matrix.
This means that the equation of equilibrium may be rewritten in the form
Substituting for the increments of acceleration and increments of velocity in terms of the increments of
displacement leads to the equation
If the damping matrix is constant, i.e. does not change with time, this equation may be simplified to give the
47
following equation
This equation may be solved for the incremental displacements. The displacement, velocity and acceleration
vectors can now be updated and the member forces at time t+)t computed giving the elastic force vector and
the damping force vector at the new time-step can also be updated. After updating the damping and stiffness
matrices the above sequence is repeated for the next time-step.
As mentioned above, this integration scheme is unconditionally stable but that does not imply that it is
unconditionally accurate. The user has the responsibility to ensure that the time-step being used is small enough
to maintain accuracy. Error will be caused by modes that have too small a natural period of free vibration to be
accurately integrated with the chosen time-step and yet have a significant contribution to the response. Error will
also be caused in systems where there are very large changes to the stiffness of the structure within the time-step
and the change in the equilibrium is not well represented by the operation of the tangent stiffness on the
increment of displacements. These errors can be reduced by either decreasing the size of the time-step, by
using Newton-Raphson iteration within each time, or by a combination of these approaches. The user therefore
should, for new types of structure or new problems outside their experience, check the answers by repeating the
analysis using a smaller time-step. If there are noticeable differences in the response then this indicates that the
time-step is not small enough and further investigation to find a time-step that is small enough to maintain
accuracy needs to be made.
In any circumstance, do not use a time-step that is greater than the time-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.
48
9.2 Explicit Central Difference Method
An alternative method is the use of an explicit Central Difference method. This method is only conditionally stable
in that the time step must be less than 0.5 of the shortest natural period of the structure. For most framed
structures this method is not very economic for earthquake type loadings and is not generally recommended.
Most framed structures have very small wave travel times between nodes, particularly along the axially stiff girder
members. This implies very short natural periods for these modes. Only a lumped or diagonal mass matrix is
permitted with this integration scheme. All degrees of freedom must have mass for this scheme to work.
The equation of equilibrium is
and noting that [K]{u} is the nodal force vector associated with the current member forces and that the second
term on the left hand side of the equation is the nodal damping force vector, rearranging and multiplying through
by the inverse of the mass matrix leads to
Using Central Differences for the accelerations in terms of the displacements at time t+)t and t-)t gives the
increment of displacement
therefore
From the expression for the velocity at time t+)t
and at time t
and therefore the increment of velocity is given by
Knowing the increments of displacement and velocity the displacements and velocities can be updated to the next
time step. The member forces can now be evaluated and transformed into the nodal force vector and the nodal
damping force vector can also be computed. The new applied force vector can be evaluated and the new
accelerations can be computed and the sequence of operations in the step above is repeated.
49
Figure 52 Geometric Stiffness Effects
10 SMALL and LARGE DISPLACEMENTS
Small displacement analyses are appropriate for most dynamic analyses. In this case the members stiffnesses
are not affected by the deformations of the structure and the nodal coordinates remain unchanged during the
analysis. RUAUMOKO can model structures where the displacements are sufficient to require a large
displacement analysis or where the axial forces in members affect their stiffnesses.
In large displacement analyses the coordinates are updated at every time-step and the stiffnesses, allowing for
changes in the axial forces in the beam or wall members and the changes in geometry in the members, are re-
computed at every time-step. This procedure is computationally expensive. but is important if the frame is
undergoing large displacements. An example would be when the interstorey drifts are significantly greater that
1% of the storey height or where the axial forces in Frame members are large.
The P-Delta option, where the displacements are assumed to be small and the coordinates are unchanged but
the beam and column member stiffnesses are adjusted for the axial forces from the static analysis. This allows
for the lateral softening of the columns due to the gravity loads. The P-Delta effect is assumed to be constant as
the increase in stiffness on one side of the structure due to overturning moments is offset by the decrease in
stiffness on the other side of the structure. This approach has a minimal effect on the cost of the analysis. This
option is only really applicable to frames with vertical columns and where the total vertical force on the columns
of a floor is constant, i.e. where the applied dynamic actions are only horizontal. In other cases the Large-
Displacement option is more appropriate.
The effect of the axial force on frame and wall member stiffness is shown in Figure 47. There are two
components, the first is the softening of the flexural stiffness of the member and the second is the 'string' stiffness
reduction of the lateral stiffness of the member. The nett effect is the same as subtracting the geometric stiffness
from the member stiffness but is computationally more efficient. The first part also accounts for the effects of
the axial forces on the member moment-rotation properties.
50
Figure 53. Total and Relative Displacement
11 RELATIVE or TOTAL DISPLACEMENTS
The program is written so that the displacements, velocities and accelerations are those measured relative to
the fixed foundation or base of the structure. If a travelling wave input is implied by setting the appropriate flags
on the nodal point data then the program will work in a total displacement, velocity and acceleration system. This
may 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 motion for a multi-degree of freedom structure subjected to a time varying load may be written
as:
where [M], [C] and [K] are the mass, damping and stiffness matrices, {v( }, {v0 } and {v} are the accelerations,
velocities and displacements of the structure and { P(t)} is the time 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 dynamic effects in the structure are caused by the motion of the
ground supporting the structure.
In the above equation, the displacements are the total displacements of the structure measured from some fixed
reference point. The usual measure of displacements in structural analyses, those relative to the ground is not
immediately applicable because the ground itself is moving. However, most engineering calculations use relative
displacements {u}, i.e. displacements of the structure with respect to its foundation, and the total displacements
can be represented by a combination of this relative displacement and the ground displacement. This is
applicable where the whole foundation of the structure may be considered as having the same imposed ground
motion.
If {u} is the displacement of the structure relative to the rigid foundation then
g
where {r} is the displacement of the structure due to a unit ground displacement and u (t) is the ground
displacement history.
51
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
52
For multiple support situations
where each column of [r] is the displacement of each degree-of-freedom due to a unit displacement of each
foundation degree-of-freedom in turn.
There will also be multiple {r} vectors if more than one directional component of the earthquake excitation is
considered in the same analysis. The reader should note that real earthquakes have three orthogonal
displacement components.
Substituting the second equation into the first gives
g g g
Given the ground acceleration u( (t) this will have to be integrated with respect to time to give u0 (t) and u (t). If
g
the ground displacement history u (t) is known it will have to be differentiated with respect to time to give the
velocity and acceleration histories of the ground.
For non-linear structures with multiple support input motions the above equation is inconvenient as the vectors
{r} may also be functions of the displacement and in that case the first equation in total displacements will be
much more convenient to use. In this case the base displacements, velocities and accelerations are known and
as the loads {P} are constant the incremental displacements of the structure can be found from a back-
substitution process in the incremental equations of equilibrium.
If the ground motion 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 displacement, then the last equation may be considerably
simplified.
For a rigid-body displacement no forces are generated within the structure. This is a necessary property of any
member or structure stiffness matrix.
If the usual assumption that damping forces are considered to be only due to relative velocities is made then
and the equation of motion becomes
g
We may treat -[M]{r}u( (t) as the effective earthquake force. Note the negative sign. The direction of the
earthquake in design calculations is not known and many earthquake loadings code equations have dropped the
sign. However, for most analyses, particularly if the relative displacements are to be combined with the ground
displacements, the sign is important. This is the equation of dynamic equilibrium that is used in most dynamic
analyses and is used in RUAUMOKO for relative displacement solutions.
If the structure is linearly elastic then the gravitational and earthquake loads may be treated separately and
combined later using the Principle of Superposition. However, if there are any non-linearities in the materials,
or in the geometry as the result of large displacements, then all the loading conditions have to be considered
together.
53
12 GENERAL PROCEDURES
12.1 Free-Format Input
All program data (except the earthquake acceleration records which are in a standard accelerogram format) is
read under a free-format control i.e. no special format for the input line is required. For help on the use of the
command processor type $HELP at any prompt. The field definition or delimiter is one or more blank columns,
an equals sign (=) or a comma (,). In general, the integer I or floating point F numbers must be provided on the
line in the prescribed sequence and trailing fields, if left blank, are interpreted as zero. The floating point numbers
may be in the usual form i.e. 267.3 etc. or an exponential form e.g. 2.673E 2, in both cases the decimal point is
optional and in the exponential case there must be no blank space between the mantissa 2.673 and the letter
E (or e). The exponent must not have a decimal point. Integer numbers must not have a decimal point. All
numbers may have plus + or minus - signs or be unsigned. Numbers may also be input in the form of arithmetic
expressions, i.e. ((2^3+5)/10) which is equivalent to 1.3 but which may indicate how it was derived, please check
$HELP for more details on the use of these expressions. An input line is terminated after reaching column 80
or on encountering an isolated exclamation mark ! i.e. the exclamation mark must be preceded by and followed
by at least one blank column. Any characters following the exclamation mark are ignored. Alphanumeric fields
or characters are automatically converted to upper case unless they are protected by single or double quotation
marks ( ' or " ). Please see the reference manual for the TinyClip command processor used by all prgrams in
the Ruaumoko suite.
A line beginning with an asterisk * in column 1 is treated as a comment line, is printed in the output file and is then
ignored. Blank lines are ignored in the input. Lines that are only for information within the data file should have
an exclamation mark ! as their first non-blank character. Any comments beyond the exclamation mark are
ignored by the reader.
The only valid characters, except for alphanumeric fields where any ASCII character is acceptable, are the digits
0-9, the signs + and -, the decimal point . and under the above conditions the symbols E, e, * and !.
In the description of the input data that follows in the latter part of this manual the following convention is used.
Each input line is designated by a box as follows:
MAXIT MAXCIT FTEST WAVEX WAVEY
where the variables MAXIT etc. are described in the lines below the box indicating the numerical 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 may be used. However, care must be exercised to ensure that ALL quantities are in
the same units. Note: in the program weights are input and internally converted to masses and that the ground
accelerations are in units of the acceleration of gravity.
12.3 Numbering
All sequences are numbered in sequences starting at 1. This applies to nodes, members, section properties,
masses and loads. All data items must be supplied in ascending order. Traditionally nodes, or nodal points, are
numbered in such a way that the nodal-point difference for any member is minimized reducing the band-width
of the stiffness matrix and the computational cost of the analysis. This is not important as the program has an
automatic mesh renumbering scheme which optimises the equation numbering. The user does not see this
renumbering as an internal look-up table relates the nodal displacements to the equation or degree-of-freedom
numbers. The difference in the original stiffness matrix storage requirement and the optimised size are output
in the statistics at the end of the analysis.
54
13 RESULTS
13.1 Initial Input Echo
All input data is printed in the output file.
13.2 Static Analysis
When any static load is placed on the structure (dead and static live load) then the displacements (translations
and rotations) of all nodes are printed as well as the internal actions (forces and moments) in all members of the
structure.
13.3 Modal Analysis
If a modal analysis is required then for each mode of free vibration the natural frequency, period and the
equivalent viscous damping implied by the chosen damping model will be printed. The mode shapes will be
printed if requested. Then for earthquake analyses the Participation Factors and the Modal Masses are
computed for all output modes. 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 displacements as well as selected member axial forces, end moments and shears may
be printed at any selected time-step interval throughout the analysis starting at the end of the first step.
In a similar manner, data may be output to a post-processing file for use in the post-processing program
DYNAPLOT.
At the end of the time-history a summary (envelopes) of the results together with maximum plastic displacements,
member ductilities and, if required, damage indices are printed. The output ends with some statistical information
on the analysis.
If the analysis terminates abnormally, check the output file for error messages. These are all included near the
end of the output file.
55
14 SIGN CONVENTIONS
14.1 Nodes - Displacements and Forces
A right-handed Cartesian coordinate system is used and the positive displacements and forces are shown below.
Right-hand screw rule implied for moments.
Figure 57. Nodal Point Displacement and Rotation Sign Convention.
14.2 Frame and Foundation Members Displacements and Forces
Axial elongations and hence tensile forces are positive. Applied moments, together with fixed end and yield
moments, are positive as shown below. A positive rotation of the equivalent plastic hinge is the result of a
positively applied moment. The sense of the positive forces and moments are shown below. A positive curvature
is associated with a positive bending moment.
Figure 58. Beam Forces and Moments Sign Convention.
56
14.3 Spring, Damper, Tendon and Contact Members
Longitudinal or x forces and deformations are positive when tensile. The Transverse or y forces and
deformations are positive when the shear at end 2 of the member is in the positive y direction and the
corresponding action at end 1 is in the -y direction. Moment and rotation is positive in the same sense as in the
1 2
beam members above noting that in these members M = M .
Figure 59. Spring, Damper, Contact and Tendon Force and Moment Sign Convention.
57
14.4 Quadrilateral Finite Element
Tensile stresses are positive and the positive shear stresses and the resultant forces and moments are indicated
in Figure 60.
In-Plane Forces/unit length
Bending Moments/unit length
Figure 60. Quadrilateral Actions Sign Convention.
14.5 Masonry Panel Elements
The strut forces are tension positive and the shear is positive when the x displacement increases as y increases.
Plate Bending Moments as for Quadrilateral Finite Elements.
58
15 GRAPHICS
15.1 On-Screen Graphics
If the program is being run in an interactive mode, such as on a personal computer or workstation then it is
possible to have the deformed 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 monochrome graphics. For the
spring members the member is drawn in three segments and the colour shown is that for each of the three
actions, the displacement springs dominating the colour choice unless only rotational springs are in use then the
rotational springs control the colour. The pictures are produced every time the plastic hinge distribution changes
if the variable KPLOT is zero or every KPLOT time steps if the variable KPLOT is greater than zero.
The use of this option slows the program down by approximately 30 per cent. For this reason it is recommended
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 members, when elastic, are shown in green. Rigid links and rigid end-blocks are shown in black.
In Frame elements plastic hinges forming with positive moments are shown in red and negative moments 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 compression, in the central region of the member.
Spring members show x, y and z yield in the first, second and third segments of the length of the member. The
force components govern unless the displacement springs are of zero stiffness when the moment components
govern the colour choices. If the member is of zero length then it is invisible. The colour choice is green, red,
blue or yellow depending on whether the member is elastic, yielding with a positive action, yielding with a negative
action or in a slack region of the hysteresis loop.
Dashpot and tendon members are invisible during the time-history analysis and contact elements are visible only
when contact is made showing red in tension or blue in compression.
Masonry panel elements are shown in yellow with the struts showing their yield status with the appropriate colours
for the equivalent spring members. The masonry panel elements, for plotting, are shrunk by 10% around their
centre of gravity to separate from the surrounding elements
The quadrilateral elements, for plotting, are shrunk by 10% around their centre of gravity to separate them from
the surrounding elements, and as they are elastic, they are green in colour.
59
Figure 61 Giberson Hinge Model
16 DUCTILITIES
At the end of the analysis the ductilities are computed for any beam or spring member that has exceeded its yield
strength during the analysis. The ductility is defined as the maximum deformation divided by the yield
deformation. For frame members the ductility is a curvature ductility. For column members, if the yield
deformation is that associated with the maximum yield moment then this means that the ductilities calculated are
the minimum possible member ductilities. .
16.1 Giberson Beams and Member Ductility
Assuming that the moment 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 member with curvature 1/r and the plastic
hinge with rotation ,.
From geometric considerations
From Moment Curvature
60
Figure 62. Giberson Beam with Hinge at End 1
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 member.
For example: assume plastic hinge at end 1 only.
61
Figure 63. Beam With Degrees of Freedom
Inverting to get stiffness matrix
This can be transformed to a beam with transverse displacement and rotation at each end by pre and post
multiplying [s] by ["] where
where L = member length.
This gives the member stiffness matrix
62
Figure 64. Cantilever Beam
If the spring flexibility is zero ie " = 0 this reduces to the normal stiffness matrix.
BEAM DUCTILITY example for a Giberson Cantilever Beam
Bi-linear factor p.
Plastic hinge length H.
Member Stiffness
63
Static condensation to remove 2 degree of freedom
as expected
Curvature
At yield
Inelastic Case
From static condensation
where
Let beam have a ductility of :
64
Plastic curvature
where pEI = current stiffness in the hinge zone.
The curvature ductility is therefore
If and
then
If a hinge forms at both ends of a beam in a frame the new member stiffness will be required with hinge flexibility
at both ends of the member.
16.2 Beam-Column Members
The ductility calculation requires a value at the yield curvature in order to compute the curvature ductility. The
axial force in column members varies during the dynamic analysis in plying available curvature calculation at any
stage. In RUAUMOKO the default yield curvature used to compute member ductilities is that associated with the
axial load in the column under the static load.
65
17 DAMAGE INDICES
If damage indices are to be computed for the beam or spring members the input requires the ultimate ductilities
for the member actions. It is implied that these are the ductilities at which the member is assumed to fail. This
has no effect during the time-history analysis but they are only used to compute the damage indices at the end
of the analysis. The number of cycles of inelastic behaviour is actually the number of times that member action
unloads from the inelastic part of the hysteresis spine curve divided by 2. A Damage Index of 1.0, assuming
proper ultimate ductilities are specified, implies failure and a value of 0.4 is about the limit of repairable damage.
[Carr 1993]
m y j u m y y h u m
Letting : , : , : , : , F , F , * ,E , E and E be the maximum, yield, cycle j and ultimate ductilities, the maximum
and yield actions, the yield displacement (curvature) and the dissipated hysteretic energy and the work done at
ultimate and maximum ductilities respectively the seven damage indices computed are:
1. Deformation
2. Park and Ang [Park 1985]
3. Bracci et al [Bracci 1989]
4: Roufaiel and Meyer [Roufaiel 1987]
5: Cosenza, Manfredi and Ramasco (Ductility) [Cosenza 1993]
6. Banon and Veneziano [Banon 1982]
7. Krawinkler and Zohrei [Krawinkler 1983]
66
18 ENERGY
The program computes 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 incremental equilibrium is:
T T
where M, C and K are the Mass, Tangent Damping and Tangent Stiffness matrices, *P is the incremental load
and *u is the incremental displacement and the dots denote differentiation with respect to time to give the
incremental velocities and the accelerations. In an earthquake analysis using a relative displacement formulation
the incremental loads are functions of the earthquake accelerogram. However, in a total displacement
formulation the right hand side of the equation has only the static loads.
At every step in the analysis equilibrium must be maintained so that equilibrium is maintained
S S
Where [C ] and [K ] are the secant damping and stiffness matrices. i.e.
Inertia Damping Elastic
where F , F , and F are the inertia, damping 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 time yields
The first term is the relative kinetic energy for relative displacement analyses and the actual kinetic energy if a
total displacement analysis is being carried out. The second term is the dissipated energy due to viscous
damping. 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 displacements
of the structure. Not all of the elastic strain energy is recoverable if the structure has undergone inelastic
deformation because there will most likely be self-equilibrating locked in forces in the structure at the end of the
analysis. To get a measure 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 completed. This is, however, seldom
performed. The program also computes separately the plastic work done during the analysis but because this
is currently computed outside the hysteresis routines it is not as accurate as the other energy terms.
It must 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 displacements and the internal strain energy is one half of the
product of the elastic forces and the displacements. This is a requirement of the Theorem of Minimum Potential
Energy. This shows as a slight offset between the sum of the terms 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
minimum in the static analysis. If, however, the difference grows during the analysis it indicates a loss of
accuracy in equilibrium and, consequently, a smaller time-step should be used and/or iteration on residuals may
be required.
67
19 REFERENCES
Baber, T.T. and Wen, 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 Dynamics, 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 Pampanin, 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. Dynamics, EURODYN'93,
Trondheim, Norway, 2123 June 1993, Moan, T. et al, Eds. Balkema, 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 Canadian Conference on Earthquake Engineering,
th
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.
Chambers, J.D. A Distributed Spring Soil Model for Dynamic Soil-Structure Interaction Analysis, M.E. Thesis,
Department 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 Ramasco, R. The Use of Damage Functionals in Earthquake Engineering: A
Comparison Between Different Methods. Earthquake Engineering and Structural Dynamics, 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. Numerical Methods in Engineering, Vol. 17, 1981,
pp 14271449.
Crisafulli, F.J. Seismic Behaviour of Reinforced Concrete Structures with Masonry Infills. Ph.D. Thesis,
Department of Civil Engineering, University of Canterbury, July 1997.
68
Crisp, D.J. Damping Models for Inelastic Structures. M.E. Report, Department of Civil Engineering, University
of Canterbury, February 1980.
Davis, R.O. Pounding of Buildings Modelled by an Impact Oscillator. Earthquake Engineering and Structural
Dynamics, Vol. 21, 1992, pp 253274.
Dodd, L. The Dynamic Behaviour of Reinforced-Concrete Bridge Piers Subjected to New Zealand Seismicity.
Ph.D. Thesis, Department 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.
Emori, K. and Schnobrich, W.C. Analysis of Reinforced Concrete Frame-Wall 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 Symposium, 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, Wairakei, 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, Department 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, Department of Civil Engineering, University of Canterbury, February 1978.
Kabeyasawa, T., Shiohara, H., Otani, S. and Aoyama, H., Analysis of the Full-scale Seven-storey Reinforced
Concrete Test Structure. Journal of the Faculty of Engineering, University of Tokyo, (B), Volume
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., Katsumata, H. and Aoyama, H. Effect of Wall Base Rotation Behaviour of Reinforced
Concrete Buildings. Proc. 3rd South Pacific Conf. on Earthquake Engineering, Wellington, 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.
69
Keshavarzian, M. and Schnobrich, W.C. Computed Nonlinear Seismic Response of R/C Wall-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 American
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. Computers and Structures, Vol. 16, No. 14, 1983, pp 531541.
Li Xinrong. Reinforced Concrete Columns Subjected to seismic Loading. Ph.D Thesis, Department of Civil
Engineering, University of Canterbury, 1994.
Liu, Aizhen, Seismic Assessment and Retrofit of Pre-1970s Reinforced Concrete Frame Structures. Ph.D.
Thesis, Department of Civil Engineering, University of Canterbury, 2001. 398p.
Matsushima, 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, December 1980.
Muto, K., Ohmori, N., Sugano, T., Miyashita, T. and Shimizu, H. Non-linear Analysis of Reinforced Concrete
Buildings. Theory and Practice in Finite Element Structural Analysis, Yamada, 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-Champaign, Nov. 1974.
Otani, S. Nonlinear Behaviour of Reinforced Concrete Building Structures Especially Under Earthquake
Motions. IASS Symposium, Darmstadt, 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 Aoyama, 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 Pampanin, 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.
70
Pyke, Robert, Nonlinear Soil Models for Irregular Cyclic Loadings. J.Geotechnical Eng.Div. ASCE, Vol. 105,
No. GT6, June1979,pp 715,726
Rahman, A.M. Seismic Pounding of Adjacent Multiple-Storey Buildings Considering Soil-Structure Interaction
and Through-Soil Coupling, Ph.D. Thesis, Department of Civil Engineering, University of Canterbury,
1998.
Ramberg, W. and Osgood, W.R. Description of Stress-Strain Curves by Three Parameters. National Advisory
Committee on Aeronautics, Technical Note 902, 1943.
Remennikov, A. and Walpole, W.R. Incremental Model for Predicting the Inelastic Hysteretic Behaviour of
Steel Bracing Members. Research Report 95-6, Department of Civil Engineering, University of
Canterbury, Christchurch, New Zealand, October 1995, p 114.
Remennikov, A. and Walpole, W.R. Analytical Prediction of Seismic Behaviour for Concentrically-Braced
Steel Systems, Earthquake Engineering and Structural. Dynamics, Vol. 26, 1997, pp 859874.
Remennikov, A.M. and Walpole, W.R. Modelling the Inelastic Cyclic Behaviour of a Bracing Member for
Work-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 Dynamics, 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, Department 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,
Department 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. Wairakei, 2729 Mar,
1998, pp 7582.
Selvadurai, A.P.S. Elastic Analysis of Soil-Foundation Interaction. Developments in Geotechnical
Engineering, Vol. 17, Elsevier Scientific Publishing Company, The Netherlands, 1979.
Sharpe, R.D. The Seismic Response of Inelastic Structures. Ph.D Thesis, Department of Civil Engineering,
University of Canterbury, November 1974.
Stewart, W.G. The Seismic Design of Plywood Sheathed Shear Walls. Ph.D Thesis, Department of Civil
Engineering, University of Canterbury, March 1987, 395p.
Taylor, R.G. The Nonlinear Seismic Response of Tall Shear Wall Structures. Ph.D. Thesis, Department of
Civil Engineering, University of Canterbury, November 1977.
Umemura, H. and Takizawa, H. Dynamic Response of Reinforced Concrete Buildings. Structural Engineering
Documents, IABSE, Zurich, 1982, 64p.
Wen, Y. Method for Random Vibration of Hysteretic Systems. J. Eng. Mech. Div., ASCE, Vol. 102, No. EM2,
April 1976, pp 249263.
Widodo. The Rocking of Multi-storey Buildings. Ph.D Thesis, Department of Civil Engineering, University of
Canterbury, February 1995, 400p.
Wilson. 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.
71
Wilson, E.L. and Penzien, J. Evaluation of Orthogonal Damping Matrices, Int. J. Numerical Methods in Engg.,
Vol. 4, 1972, pp 510,
Wolf, John P. Foundation Vibration Analysis Using Simple Physical Models. Prentice Hall, Englewood Cliffs,
NJ, 1994.
Zhu, K., Al-Bermani, 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, September 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, Department 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.
1
RUAUMOKO-2D EXAMPLES
1 Earthquake Response
The file EXAMPLE.DAT is the data file describing a small 4 storey timber frame. The frame geometry is
shown on page 3 together with a listing of the data file. The frame has columns which are continuous over the
four storeys, they are assumed to remain elastic and are pinned to the support at their bases. The four
girders are connected to the columns by steel nail plates which are assumed to be elasto-plastic and yield at
a moment of plus or minus 40 kN.m. Both member self weight contributes to the mass of the frame as do
nodal point masses representing the mass of walls in the out of plane direction of the frame and which act at
the nodal points. There are also initial member 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
displacements and forces cannot be added to the dynamic response later as the principle of superposition is
no longer valid.
The frame was subjected to 10 seconds of the North-South component of the May 1940 El Centro
earthquake accelerogram. This is contained in the file EL40NSC.EQB. This file is in the BERG format where
each line contains 4 time-acceleration pairs of data and the total duration of the record is 20 seconds.
The file EXAMPLE.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 modal analysis and the enveloped results
of the time-history analysis as the frame is subjected to the El Centro earthquake. The member deformations
and the ductilities are also shown and finally the damage indices are computed for the beam members. The
final output section is the statistics from the analysis which shows how much array space etc. was used in the
analysis.
The pages following the output from the analysis also show some of the print-screen pictures from the
analysis. The first is a picture of the mesh followed by the earthquake excitation history. The next two pictures
are two of the mode shapes of the structure. These mode shapes are not used in the analysis except for non-
Rayleigh damping models when they are used to construct a damping matrix, but they provide the user with
some confidence that the structure being analysed is correctly modelled 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 modes of free-vibration. The final picture is a snap-shot of the displacement at time =
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 EXAMPLE.RES which was produced by
RUAUMOKO during the time-history analysis. The file has stored the data for all nodes and for all members
at an interval of 0.05 seconds (every 5 time-steps). The first plot is of the lateral displacements of nodes 9
and 3. The second plot is the bending moment at the left hand end of the first floor beam and the next plot is
the hysteresis plot showing the bending moment versus the curvature in the beam. Though the hysteresis is
meant to be elasto-plastic some of the corners appear to be rounded off but this is because DYNAPLOT has
no knowledge of the hysteresis rule, just the moment and curvature at each saved time-step, and it draws a
straight line from point to point. Even if results were saved every time step the curtailing of the corners will not
be completely eliminated. As a general rule, if you wish to plot hysteresis loops the results should be saved at
very small time-intervals. The consequence is very large .RES files. For normal time 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
2
elastic while if it is 0% the end of the member is perfectly plastic. The final plot is the time-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 damping, the third line shows the sum of the relative
kinetic energy, the energy dissipated by the damping and the elastic energy and the last line is the applied
input energy. There is always a small 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 time step is being
used or iteration on residuals should be enabled so that equilibrium is better maintained during the analysis.
To run these examples yourself take the following steps. All responses are completed by following them by
the RETURN or ENTER key.
1 Run the program RUAUMOKO-2D by giving the command RUAUMOKO2D followed by ENTER.
2 for the output listing file type EXAMPLE.LIS or any other file name that you wish i.e. JUNK. If the file
name already exists you will be asked if you wish to over-write it or try for a new name.
3 At the prompt for the first excitation file type EL40NSC.EQB assuming that it is in the current
directory. If not prefix the file name 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 name for the .RES file for post-processing in DYNAPLOT. The default
name is the same as the output listing file but with the extension .RES. If this is satisfactory just hit
the ENTER key otherwise respond with a suitable name. The extension .RES will be added
automatically.
6 You are then asked if you want the on-screen graphics. Respond with y or yes.
7 The next prompt asks if this is a data check run. To get the default NO just hit the ENTER key.
8 At the next prompt which asks for the title for the analysis type $ADD EXAMPLE.DAT assuming that
this file is in the current directory. If it is not in the current directory prefix the file name with the
appropriate path.
9 The next prompt will ask if you want colour graphics.
10 When the mesh 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 message will ask which mode you wish to see. If you wish to see none just hit the ENTER
key else type any number 1 to 4 followed by the number of cycles (optional) then ENTER to see that
mode shape. After the number of cycles (default is five) and a quarter cycle the picture will freeze. To
return to the mode shape selection his the ENTER key.
13 When the time-history commences the displays of the deformed 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 completed.
3
4
5
6
7
8
9
10
11
1 If you wish to run the post-processor program DYNAPLOT type the command dynaplot. This
program has good built-in help files.
2 The first prompt is for the output file. Just hit the ENTER key to get the default screen output.
3 The next prompt is for the name of the post-processor file. The response is the same as the
response to point 6 in the RUAUMOKO input. Do not include the extension .RES in your file name. If
an ASCII file type was used DYNAPLOT will first search for an extension .RES then for an extension
.RAS.
4 The next prompt is Do You Want Colour. Again respond with ENTER if yes but with n or no if not, for
say, print/screen capture.
5 To produce the displacement plot for the fourth and first floors follow the following steps.
i Number of lines is 2.
ii Respond to the selection of graph type with t or time.
iii Select Node.
iv Select 1, the x-displacement.
v The Nodes are 9 3.
vi Time-step is the default 1.0.
vii The time range is the default 0 10 implying from 0 times 1.0 to 10 times 1.0 seconds, i.e.
plotting from 0.0 to 10.0 seconds.
viii The y-axis interval is the default 0.0 which means that the program will automatically select a
suitable interval based on the function to be plotted.
ix The number of y-axis grids, use the default -1 1. This implies only one interval each side of
the time 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 TIME as the space would terminate the sequence and the text would be upper
cased automatically.
xii The y-axis tile could be Displacement Nodes 9 and 3'.
6 The graph should now be plotted. In Microsoft Windows operating systems use the file pull-down
menu and select the Save or Print options. On unix GKS graphics if hard copy has been enabled
select the Hard Copy option. When you have finished press the ENTER key to return to the main
menu.
7 Another graph option may be selected or the default choice is to return to the operating system.
12
13
14
15
2 Pushover Analysis
The dynamic loading option may be used to study the response of structures to gust loading, blast loading or
even cyclic loading. To do so the user must obtain or generate an equivalent loading history and must also
know the distribution of the loading on the structure.
Another use of this option is the pushover analysis. In this case a monotonic increasing load is applied to the
structure until the ultimate 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 maximum load should not exceed the
maximum capacity of the structure as this may lead to failure of the analysis. In a pseudo dynamic analysis
this is not quite so important as it will take time for the structure to collapse as the inertia will provide some
constraint. The ramp function may be linear as in the example shown or possibly of the form
L
where T is the duration of the loading and which should be long when compared with the fundamental period
of the structure.
The loading distribution chosen in the example in the file PUSHOVER.DAT is the seismic 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 times the height at that level divided by the sum of the weight times the height at each level
summed over the whole structure. This is approximately a linear distribution from zero at the bottom to the
maximum at the top. The remaining 8% of the base shear is added to the top level forces to allow for higher
mode effects. The results show that for a maximum Base Shear of 30 kN plastic hinges have formed at the
ends of the lower three girders and the displacements are starting to increase rapidly with increase in the load
showing that the structure is almost at its ultimate load carrying capacity. The plot of the top floor
displacement shows only a very small oscillation meaning that the inertial effects are small. The duration of
the ramp function is almost 11 times the fundamental natural period of
the structure. The ramp function could possibly be applied more rapidly and a larger time-step could have
been used.
The same 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 time-steps (load-steps) earlier.
In this example the excitation has been included in the input data file but if many pushover analyses are to be
performed then such excitations could be placed in a library of earthquake accelerograms. The ramp length
may be changed by varying the variable DELTAT in the data line 23b of the RUAUMOKO-2D manual.
The plot of force versus displacement is obtained using the Base Shear plot option of DYNAPLOT where the
vertical axis is the Base Shear (the combination of the shear at end 1 of members 1 and 5) versus the top
floor displacement (x-displacement 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.
16
17
18
1
Department of Civil Engineering COMPUTER PROGRAM LIBRARY
Program name:
ASCII data
Program type:
History Output from RUAUMOKO
Program code:
ANSI Fortran77
Author:
Athol J Carr
Date:
April 29, 2007
ASCII post-processor files for DYNAPLOT.

(for programs compiled after 27th August 2001)
There is an option to use an ASCII post-processor file instead of the normal 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 programs. Though Ruaumoko
and the other programs are written in Fortran you may use any programming language to generate you own
post-processing program, i.e. Visual Basic, C, Java etc.
Ruaumoko-2D
If the control parameter IFMT on data line 2 of the Ruaumoko-2D input data (please see the user manual) 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 parameter IFMT on data line 5 of the Ruaumoko-3D input data (please see the user manual) 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 normal, 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 parameter
NSPACE, see later.
The ASCII post-processor file will be about twice the size of the equivalent BINARY file but may be useful for
users carrying out a large number of production parameter study analyses and who wish to to write a
program to extract some particular result items for comparisons between the analyses.
2
Programming language.
The programs are written in ANSI standard FORTRAN and output is under the control of the FORTRAN write
formats. The file uses a maximum line length of 128 characters and should be readable with WordPad or
equivalent in Microsoft Windows operating systems. View.com or More may also be used to view these files.
You may have to scan the longer than 80 character lines, depending on the screen settings on your
computer.
Each WRITE statement 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 items are provided for in a line in the FORMAT and 38
items are listed in the write command then the next 3 lines will have 12 numbers and the fourth line will have
the last 2 numbers of the set of 38 numbers.
Fortran Formats.
The FORMAT n I m means n integers each taking m characters or spaces. In FORTRAN all data is
right-justified, i.e. all numbers are packed to the right of the field m. e.g. 6 I 5 means 6 i ntegers having 5
columns each in a total of width of 30 columns, or character, across the line.
The FORMAT n F m.i means n floating point numbers each taking m characters or spaces with i digits after
the decimal point. If the number is too large for the field m then one gets a row of m asterisks, *, and if it is
too small, i.e. more than i zeroes after the decimal prior to any significant digits, one gets 0.0.
The FORMAT n E m.i means n floating point numbers each taking m characters or spaces with i digits after
the decimal point. The number is in scientific or exponent form, the first space is for the sign followed by a
zero, a decimal 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 number ahead of the letter E must be multiplied by to get the
actual data item. With this format then no matter how large or small the number is always readable. If the
FORMAT is preceded by a 1P i.e. 1P12E10.3 means that the exponent has been reduced by one and that
the zero ahead of the decimal point has been replaced by a digit. This means that the number has not been
altered just that one more significant digit is available. The 1P holds for all remaining E or F formats in the
FORMAT statement, the I formats are not affected. Note, in the E format the m must be at least 7 greater
than the i.
The FORMAT n X means n blank spaces.
The FORMAT A n means n alphanumeric characters.
A / (forward slash) in a Format statements means move to new line.
When the range of a Format is exceeded without writing all of the items the format starts again at the
beginning.
Note: The structure of the binary file is similar to that of the ASCII file but some of the initial parameters
are re-ordered. For this reason do not attempt to write a program to read the binary post-
processor files.
3
Parameters:
LUN3 = Logical Unit Number of Output Device (File number) (=3)
NNP = Number of Nodes
NMEM = Number of Elements
NPRES = Number of Nodes saved in .RAS File
NMRES = Number of Elements saved in .RAS File
IPVERT = see Ruaumoko-2D or Ruaumoko-3D manual
NBASE = Number of Base Excitation degrees of freedom,
Travelling wave input only, else = 0.
If NBASE = 0
then the displacements, velocities and accelerations are Relative to the foundation,
else,
the displacements, velocities and accelerations are Total displacements, velocities
and accelerations.
NLR = Number of Dynamic Input Excitations
(Earthquake analyses = number of components)
(Dynamic force analyses = number of force histories)
(Adaptive Pushover = 1)
(IPANAL = 8 or 9 = number of displacement histories)
NMODE = Number of Mode Shapes available to Dynaplot.
NEP = Number of Equations/Node. Ruaumoko-2D = 3, Ruaumoko-3D = 6.
NSPACE = Number of Space Dimensions. Ruaumoko-2D = 2, Ruaumoko-3D = 3
JOUT = Output Flag. Not used any longer. Ruaumoko-2D = 0, Ruaumoko-3D = 0
TK = Time Interval between post-processor file write statements
TIME = Duration of excitation (Initial input value)
PLOT = 19 term array for graphics information. In Ruaumoko-2D only the first 3 are used
DT = Ruaumoko-2D and Ruaumoko-3D time-step
KPOST = Number of time steps between saves to post_processor file
Ruaumoko-2D = KPA see Ruaumoko2D user manual,
Ruaumoko-3D = KPOST see Ruaumoko3D user manual.
N = Number of items written for member I
MPLOT = Packed plot flag for members, a 1 to 6 digit integer.
I,J,K,M are Integer indices
4
Element Data retrieved.
If L = element number
NP(1,L) = Node I of element
NP(2,L) = Node J of element
NP(3,L) = Node K of element
NP(4,L) = Node L of element
NP(5,L) = IOUT for Element.
(if = 0 or 1 replaced with number of items/element, else = 0)
(if IOUT is 2 or 3 this element's data is not written to the post-processor file)
NP(6,L) = 5 digit compacted integer IHYST//ITYPE//LTYPE
IHYST (first 2 digits), 0-49 (Hysteresis rule number)
ITYPE (third digit) element sub-type
i.e. 1=Giberson Beam
2=Concrete Beam-column
3=Steel Beam-column
4=General Beam-column
5=Two-Component Beam
6=Variable Flexibility Beam
7=4 Hinge Beam (Ruaumoko-2D)
7=Alternative Concrete Beam-column (Ruaumoko-3D)
9=Beam or Beam-Column with In-elastic shear
LTYPE (fourth and fifth digits) element type
i.e. 1=frame member
2=spring member
3=wall member (Ruaumoko-2D only)
4=damper member
5=tendon member
6=contact member
7=quadrilateral finite element
8=masonry panel element
9=foundation member
BEND1,BEND2 = Rigid End-block lengths of Frame elements, else 0.0
5
STRUCTURE data saved at each KPOST save step:
a:Ruaumoko-2D.
FT( 1) = TIME (written as two integers, Number of whole seconds and Number 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 Displacement
FT( 7) = Y ground Displacement
*Dynamic 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) = Damping Work Dissipated
FT(10) = Strain Energy
FT(11) = Applied Work Done
FT(12) = Plastic Work (Approximate)
FT(13) = Effective Ductility (Only useful in Pushover analyses)
FT(14) = Effective X displacement (Only useful in Pushover analysis)
FT(15) = Effective Y displacement (Only useful in Pushover analysis)
FT(16) = Total applied X forces
FT(17) = Total applied Y forces
FT(18) = Total applied Z moment about origin (X=0,Y=0)
Note: This saving of time as two integers means that the shortest time step that may 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 time-step (this should be adequate for most analysts). The earlier versions had trouble
with either long duration records (>1000 seconds) and/or with small steps due to the single precision saving
of the data (7 decimal digits). This new version may mean 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
b:Ruaumoko-3D
FT( 1) = TIME (written as two integers, Number of whole seconds and Number 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 Displacement
FT( 9) = Y ground Displacement
FT(10) = Z ground Displacement
*Dynamic 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) = Damping Work Dissipated
FT(13) = Strain Energy
FT(14) = Applied Work Done
FT(15) = Plastic Work (Approximate)
FT(16) = Effective Ductility (Only useful in Pushover analyses)
FT(17) = Effective X displacement (Only useful in Pushover analysis)
FT(18) = Effective Y displacement (Only useful in Pushover analysis)
FT(19) = Effective Z displacement (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 moment about origin (Y=0,Z=0)
FT(24) = Total applied Y moment about origin (Z=0,X=0)
FT(25) = Total applied Z moment about origin (X=0,Y=0)
Note: This saving of time as two integers means that the shortest time step that may 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 time-step (this should be adequate for most analysts). The earlier versions
had trouble with either long duration records (>1000 seconds) and/or with small steps due to the single
precision saving of the data (7 decimal digits). This new version may mean 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.
7
NODAL POINT data saved at each KPOST (or KPA) time steps:
(see IOUT in manual to identify which nodes save data)
a:Ruaumoko-2D
I = nodal point number
FT( 1) = X displacement
FT( 2) = Y displacement
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 moment
FT(13) = X damping force
FT(14) = Y damping force
FT(15) = Z damping moment
FT(16) = X inertia force
FT(17) = Y inertia force
FT(18) = Z inertia moment
8
b:Ruaumoko-3D
I = nodal point number
FT( 1) = X displacement
FT( 2) = Y displacement
FT( 3) = Z displacement
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 moment
FT(23) = Y applied moment
FT(24) = Z applied moment
FT(25) = X damping force
FT(26) = Y damping force
FT(27) = Z damping force
FT(28) = X damping moment
FT(29) = Y damping moment
FT(30) = Z damping moment
FT(31) = X inertia force
FT(32) = Y inertia force
FT(33) = Z inertia force
FT(34) = X inertia moment
FT(35) = Y inertia moment
FT(36) = Z inertia moment
9
ELEMENT data saved at each KPOST (or KPA) time steps:
(see IOUT in manual to identify which elements save data)
a: Ruaumoko-2D
I = element number
MPLOT = 5 digit compacted plot flag
K = Number of element Data Items
FT = 17 items for Beams (27 if 4 node Beams) (21 if inelastic shear)
Axial force, Axial displacement, Axial stiffness,
Axial Energy, Axial damage Index, Moment @ 1,
Curvature @ 1, Stiffness @ 1, Energy Flexure @ 1,
Damage Index@1 Moment @ 2, Curvature @ 2,
Stiffness @ 2, Energy Flexure @ 2 Damage Index@2
Shear @ 1, Shear @ 2
(plus for 4 node beam)
Moment @ 3, Curvature @ 3, Stiffness @ 3, Energy @ 3,
Damage Index@ 3
Moment @ 4, Curvature @ 4, Stiffness @ 4, Energy @ 4,
Damage Index@ 4
(or plus for in-elastic shear)
Shear Displacement @ 1, Shear Stiffness @ 1,
Shear Displacement @ 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 items for Springs
Longitudinal force, Transverse Force, Moment
Longitudinal Disp., Transverse Disp. Rotation
Long. % Stiffness, Trans.% Stiffness, Rotn. % Stiffness
Longitudinal energy, Tranverse Energy, Rotational Energy
Longitudinal Damage, Tranverse Damage, Rotational Damage
= 13 items for Walls
Axial force, Axial displacement, Axial stiffness,
Moment @ 1, Curvature @ 1, Stiffness @ 1,
Moment @ 2, Curvature @ 2, Stiffness @ 2,
Shear @ 1, Shear @ 2,
Neutral Axis @ 1, Neutral Axis @ 2
= 6 items for Dampers
Longitudinal force, Longitudinal velocity
Transverse force, Transverse velocity
Rotational moment, Rotational velocity
= 2 items for Tendons
Longitudinal force, Longitudinal displacement
= 5 items for Contact Elements
Longitudinal force, displacement, % stiffness,
Transverse force, displacement
= 12 items 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
10
= 15 items for Masonry Panels
Force, displacement, % stiffness for Strut 1
Force, displacement, % stiffness for Strut 2
Force, displacement, % stiffness for Strut 3
Force, displacement, % stiffness for Strut 4
Force, displacement, % stiffness for Shear strut
= 24 items for Foundation Elements
For each of the 8 Winkler springs: (2 axial springs, 4 normal springs and 2 shear springs)
Longitudinal force, displacement, % stiffness,
Transverse force, displacement, % stiffness,
= 30 items for Multi-spring Elements
Longitudinal force, Transverse Force, Moment
Longitudinal Disp., Transverse Disp. Rotation
Long. % Stiffness, Trans.% Stiffness, Rotn. % Stiffness
Transverse shift of neutral axis
For each of the 10 springs that make up the multi-spring member:
Longitudinal force and Longitudinal displacement
= 30 items for Compound Spring Elements
Longitudinal force, Transverse Force, Moment
Longitudinal Disp., Transverse Disp. Rotation
Long. % Stiffness, Trans.% Stiffness, Rotn. % Stiffness
Transverse shift of neutral axis
For each of the 10 springs/dampers/tendons that make up the compound spring member:
Force and Displacement
11
b:Ruaumoko-3D
============
I = element number
MPLOT = 5 digit compacted plot flag
FT = 24 items for Frame members (44 if In-elastic shear) (damage Index is Park and Ang)
Axial force, elongation, % stiffness, energy, Damage Index,
Moment z-z @ 1, curvature z-z @ 1, % stiffness, energy, Damage Index,
Moment z-z @ 2, curvature z-z @ 2, % stiffness, energy, Damage Index,
Torque, twist, % stiffness, energy, Damage Index,
Moment y-y @ 1, curvature y-y @ 1, % stiffness, energy, Damage Index,
Moment y-y @ 2, curvature y-y @ 2, % stiffness, energy, Damage Index,
Shear y @ 1, Shear y @ 2,
Shear z @ 1, Shear z @ 2.
(plus for in-elastic shear)
y-Shear Displacement @ 1, y-% Shear Stiffness @ 1,
y-Shear Displacement @ 2, y-% Shear Stiffness @ 2,
z-Shear Displacement @ 1, z-% Shear Stiffness @ 1,
z-Shear Displacement @ 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 items for Spring members
x force, y force, z force,
x moment, y moment, z moment,
x deformation, y deformation, z deformation,
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. damage index, y disp. damage index, z disp. damage index,
x rotn. damage index, y rotn. damage index, z rotn. damage index.
= 18 items for Damper members
x force, y force, z force,
x moment, y moment, z moment,
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 items for Tendon members
x force, x displacement.
=18 items for Contact Elements
x contact force, y friction force, z friction force,
x damping force, y spherical force, z spherical force,
x axial displacement y lateral displacement, z lateral displacement,
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 items for Quadrilateral finite elements (forces and moments 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
12
= 27 items for Masonry Panel elements
Force, displacement, % stiffness for Strut 1
Force, displacement, % stiffness for Strut 2
Force, displacement, % stiffness for Strut 3
Force, displacement, % stiffness for Strut 4
Force, displacement, % stiffness for Shear strut
Mxx, Myy, Mxy at Node I (moments per unit length)
Mxx, Myy, Mxy at Node J
Mxx, Myy, Mxy at Node K
Mxx, Myy, Mxy at Node L
= 24 items for Foundation Elements
For each of the 8 Winkler springs: (2 axial springs, 4 normal springs and 2 shear springs)
force, displacement, % stiffness,
= 39 items for Multi-spring Elements
x force, y force, z force,
x moment, y moment, z moment,
x deformation, y deformation, z deformation,
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 make up the multi-spring member:
Longitudinal force and Longitudinal displacement
= 60 items for Compound Spring Elements
x force, y force, z force,
x moment, y moment, z moment,
x deformation, y deformation, z deformation,
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 make up the multi-spring member:
Force and Displacement
= 30 items for External Elements
either:
x force, y force, z force,
x moment, y moment, z moment,
x deformation, y deformation, z deformation,
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 moment end 1, z moment end 2,
torque, y moment end 1, y moment end 2,
x axial deformation, 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).
13
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 ***********************************************************************
TINYCLIP
An Interactive Command Processor.
Athol J. Carr
Traditional Fortran programs were run in a batch mode with the input data coming from an input file where the
data was set out in a fixed format as described in some form of user document. Modern programs designed for
use on personal computers or workstations generally operate in an interactive mode and the stilted fixed format
does not lend itself to interactive operation. Although Fortran77 introduced the concept of a Free Format input
this does not provide an interactive input as the data on a line must be of the correct type, i.e. if the input variable
is of type integer then an integer number must be provided. In an interactive mode the program must be able
to accept the typed input and then examine it to determine what action to take. If the input is not of the expected
form then the program must be able to prompt for the correct information. However, the program should be
capable of running in a batch, or non interactive, mode as well.
TinyCLIP is an interactive command processor for use in programs 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 example, 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 may 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 transformations have been performed:
1. Lower case letters have been converted to upper case. (to simplify 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 implementation of TinyCLIP let us look at the interface. In what follows, the term processor
denotes the program that calls TinyCLIP to get its command input from the user.
Asking for Commands
The processor asks for a command by invoking the "get the next command" entry point CLREAD as illustrated
by
CALL CLREAD(' Enter Command : ',' ')
CLREAD has two character-string arguments. The first argument is the command prompt. If you are running
the program interactively, the following prompt text will appear on the screen:
Enter Command :
and the reader will wait for your response. The second argument is the command 'splash' which may be used
to provide extra information to the user. If the splash is non-blank then it will be displayed above the prompt.
On return from CLREAD you are entitled to assume that the user has typed something that looks like a
command. If the user just types a carriage return, or a blank line, CLREAD will keep on prompting. The policy
"don't come back until you have something to show" is (for psychological reasons) usually the right one in
interactive work.
Accessing Item Information
On return from CLREAD the alleged command 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 command. TinyCLIP provides seven
Fortran functions for information 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 number of items in the last command read.
The function CCLTYP returns the type of the ith item as follows: A for character string (alphanumeric item), I for
integer, and F for floating point.
Items are separated by blanks, commas or equals signs. For some processors whose input may contain numeric
lists it is convenient to be able to test for item separators so that
1 2 3 4 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 named xCLVAL return values of the ith command item in the type implied by the function
name. If the item is alphanumeric, 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 mode retrieval is acceptable for numeric items, and the usual Fortran conventions apply. For example,
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 numeric item, it returns blank, and if a numeric function is tried on an alphanumeric item,
it returns zero.
Some 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 delimited string are significant, including
blanks, and an apostrophe may be represented by repeating it. Arithmetic expressions are delimited by
parentheses and evaluated according to the usual Fortran rules (but ^ is the exponentiation operator instead of
**). Blanks inside an arithmetic expression are ignored.
The maximum length of a line is 132 characters and the maximum number of items on a line is 100. A line may
be terminated by placing an isolated exclamation sign ! on the line. Anything on the line following the exclamation
sign is ignored by CLREAD.

Prompts
The character string for the prompt 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 means that the prompt is displayed on
the next line on the screen, a 1 causes one blank line to be inserted ahead of the prompt and a 2 causes two
blank lines to precede the prompt.
If part of the prompt contains items inside enclosing square brackets i.e. [ Default1 Default2 ] then the items
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 may be useful in some programs where
commonly used responses can be arranged as defaults to minimise typed input from the user. The prompt is
not displayed if the processor is running in a "batch" mode or if the input is coming from an ADD file which is
described in the section on Directives below.
Splashes
If information about the expected response to a prompt 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 same way as for the prompt above.
A new line may be specified by the double ampersand &&. Such an && must 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 command this may be done by calling the
subroutine CLSHOW
CALL CLSHOW(' any splash you want')
If the information is coming interactively from the keyboard then the splash will appear on the screen. If the
information is being read in a "batch" mode, or from an ADD file, then the splash, like the prompt in CLREAD will
not be displayed.
Comparing Commands
Tinyclip has a logical function CMATCH which may used to compare commands. This function has two character
string arguments. The first, key1, is the alleged command and key2 is the command against which key1 is
tested.
Key1: The alleged key, all characters must be upper case. It may contain masking characters % and * with the
usual VAX meanings, however, * is only acceptable as a first or last character. Key1 is terminated by a
blank, period, or string exhaustion.
Key2: Internal key, consisting of a root+extension. The root must be in upper case and the extension is in lower
case or separated by a ^. Key2 is terminated by a blank, a period, or string exhaustion.
CMATCH first compares the root characters, and reports failure if no match. If root match is achieved, it
continues comparing extension characters until: (a) a mismatch is found; (b) either key is exhausted; or (c) a
blank is found in either key.
If a match is found CMATCH is .TRUE. otherwise .FALSE. For example;
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 comment line. This line is then output to the
standard output device, the screen in interactive mode or, by default, logical unit number 6 if in "batch" mode.
If the processor is to make use of the comment feature then a call to subroutine CLINIT(LPU) should be made
before any calls to CLREAD. The integer LPU is the logical unit number for the processor's listed output if it is
different from the default value. If there is an isolated (preceded and followed by blanks) exclamation sign (!) On
a line then the exclamation sign and anything else on the line is ignored by TinyCLIP. This is, in effect, a means
of terminating the line and if the data is coming from a $add text file, then notes may be added to the line after
the ! as user information. If the exclamation 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 items on a line are blanks, commas (,) or equal signs (=). Care must be taken that commas
are not used as decimal points, as is common practice in parts of Europe. TinyCLIP, as is normal in FORTRAN,
uses the stop (.) as the decimal point.
Directives
TinyCLIP recognises a series of Directives from the user. These command TinyCLIP to undertake specified
actions. The Directive must be the first command on the line and the first character of the directive is the $ sign.
This means that the processor may not use the $ as the beginning of any other command as it will be taken as
the beginning of an illegal Directive. Some directives are followed by a file name, and path unless it is in the
users current directory. The file name and path must follow the file name convention of the users operating
system.
$TYPE <filename>. In interactive mode, this will display the contents of <filename> on the screen. In
"batch" mode, it is ignored.
$ADD <filename>. Transfers input from the interactive user, or "batch" input file, to the file <filename>. 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 coming 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 terminated. 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 <filename> All responses to CLREAD are logged into the named 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 means that large data files may 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 themselves are not logged.
$ENDLOG Stops Logging of data above. Inserts a $EOF Directive at the end of the Log file.
$DLOG Removes last record from the LOG file.
$HELP Provides HELP on the TinyCLIP Command Processor. This is in addition to any HELP
files that may be provided in by the program itself. The TinyCLIP Help file covers
separators, file names, numbers 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
arguments) at the end of your program. This ensures that all ADD or LOG files are closed before the program
terminates. Some operating systems do not save a file which is created within a program if it is then not closed
prior to the program execution terminating.
If the program wishes to remove the last record stored in a LOG file, for instance when the program recognizes
that the input was erroneous then that record may be removed by a call to subroutine CLDLOG (which has no
arguments) 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 command line is required then this may be achieved by a call to the subroutine
CCLGET. The subroutine has two arguments, the first is an integer N which is the number of characters from
the command 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 must be greater than or equal to N.
Messages

Another powerful language extension vehicle is the message. A message is a command or directive submitted
by the processor. To give an example, suppose that when the processor starts it realizes that it is running in
batch mode and wants to turn on the echo printing. To do this it calls a 'mailbox' entry point CLPUT and places
a message containing an ECHO directive:
CALL CLPUT('$ECHO')
The argument of CLPUT is a character string containing the message text. The message is processed exactly
as if it was a command typed by the user, and the net effect is that the echo is turned on. The message provides
an elegant tool to achieve input-device independence.
Holding Input
Suppose that in running the processor a situation is encountered where a command is discovered which really
should have been detected further up your program tree and to prevent passing flags back to say that this
command has already been found you may call the CLPUT with a blank text to retain the current input in the
buffer to be read at the next prompt in the processor. On the next call to CLREAD this input is read from the
buffer instead of CLREAD prompting for the normal input.
As an example, suppose SOMEFLAG is the key-command 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 module should complete its tasks and then proceed to the part of the program in which that
particular command SOMEFLAG is expected. The next call to CLREAD will not display the prompt as TinyCLIP
has been informed that the appropriate response is already in the command buffer.
Utilities
There are several utility functions and subroutines that form part of the TinyCLIP library and which the
programmer may 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) determines 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
mode the integer variable MODE equals 2, while if the processor is being run in a "batch" mode, 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" mode or the input is coming from an ADD
file then the returned value is .FALSE.
The Integer function ICLFIL() returns the value of the logical unit number of the current input device, 0 from the
keyboard, 5 if the input is in 'batch' mode and 99 if from an ADD file.
Calculator
TinyCLIP has a built-in reverse-polish-notation (rpn) calculator that enables arithmetic expressions to be read
as input numbers. The example on page 1 shows how this may be used. The input line was
set value = (10/3)
The first two items are of type character and the equals sign, like blanks, is taken as a separator and the third
item is read as the numerical value 0.3333. The arithmetic expressions must be enclosed with matching
parentheses () and the items enclosed within the parentheses must satisfy the rules for the calculator input. Any
included parentheses must be in matching pairs. Invalid expressions are taken as character strings and have
a numerical value of zero. Blanks inside the expressions are ignored.
The operators are:
+ for addition,
- for subtraction,
* for multiplication,
/ for division,
% for integer division,
^ for exponentiation.
TinyCLIP uses Reverse Polish Notation for carrying out the operations and the normal FORTRAN priorities for
precedence of operations. The order of operations may be controlled by enclosing sub-operations in parentheses.
Examples;
(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 mode the logical unit numbers for both input and output are 0. If the processor is running in batch
mode then the input logical unit number is 5 and the output logical unit number is 6. The ADD files are read from
logical unit number 99 and the LOG files are created on logical unit number 98. The user should be careful in
the assignment of logical unit numbers to avoid 98 and 99. Logical unit 6 may be quite safely used for normal
output as it will cause no conflict with TinyCLIP but do not use it for other input/output purposes. The comment
lines, and any error messages, are output to the output units 0 or 6 as outlined above. The comment lines may
be directed to another output device by a call to subroutine CLINIT as was described earlier under the heading
Comments 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 number of that output file should be different to that of the default standard
output stout (stout is usually FORTRAN file 6). If the default logical unit number of stout is used then the
prompts and splashes, which are meant to be sent to the screen, are also captured by the standard output file
and the prompts are invisible to the user at the keyboard.
Unix and Linux Operating Systems
Users on unix or linux operating systems should be careful when specifying file names for the $add and $log
directives. TinyCLIP upper-cases all character strings and as file and directory names are case-sensitive in these
operating systems the user should enclose files names in quotes to retain the case of alphabetic characters in
the names.
HELP Files
TinyCLIP provides an easy way for the programmer to add HELP files to his processor. The programmer has
to write a subroutine CLHELP(TOPIC) which has as its only argument 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 prompt is HELP or ? followed by an optional character string TOPIC then
TinyCLIP goes to the CLHELP subroutine, attempts to match the TOPIC, if present it then writes to the screen
the information about that topic, and then prompts for any other TOPIC. If the user responds with a carriage
return (blank line) TinyCLIP returns to CLREAD which again displays the original prompt. An example of a help
file is shown on the next page. All calls to the HELP routine or any responses to prompts within the HELP files
are not Logged in the LOG files if Logging is in process.
If the programmer wishes he/she may 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 made to CLHINT(' ') which will provide no default hint for future calls to HELP.

It is recommended that the information supplied on a topic not exceed eighteen or so lines as this is all that may
be displayed without the first lines disappearing as the request for further topics appears at the bottom of the
screen. If further information 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 information.
Acknowledgement and Reference
The original form of the TinyCLIP package came from a paper "A command reader for interactive programming"
by Carlos A. Felippa, Engineering Computation, Vol 2, No. 3, September 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