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 W all 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 W ithout 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

W ilson 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.

W ork 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. W ith 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. W hether 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 jdamping is 8 and 8 at modes i and j with natural circular frequencies T and T respectively then

and

nThe 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

ba and the computationally awkward matrix products involved. W ilson and Penzien [W ilson 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 W ilson 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

iwhere 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 W ilson 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. W ith 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.

W hen 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 assum ing a tangent damping

matrix is used.

4. As for model 2 above but using a tangent stiffness Rayleigh damping assum ing 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 W ilson 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 W ellington city, the capital of New Zealand. This means that

the Pacoima Dam acceleration record is stronger than a design level earthquake for W ellington.

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. W hich 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 W indows 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 W ilson 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 W ilson 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. W hen 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 Newmark’s 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. W hen 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 W ilson-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 structure’s 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 W inkler 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 W all-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. W ith 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 W ilson and

Dovey [W ilson 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 W ayne 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. Muto’s Degrading Stiffness Hysteresis Rule

Figure 40. Fukada Hysteresis Rule

Figure 38. Degrading Bi-linear Hysteresis Rule

34

Figure 41. Mehran Keshavarzian’s 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 Stewart’s Degrading Stiffness Hysteresis Rule

The very general rule developed by Wayne Stewart [Stewart 1987] shown in Figure 43 was initially developedto model nailed-plywood sheathed structural walls but has also been successfully used to model reinforcedconcrete 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 masonrywall units. By selecting suitable parameters other systems may also be modelled. A similar model has beenproposed by Widodo [Widodo 1995] to represent foundation compliance springs. Another non-linear elasticrule follows a bi-linear yielding relationship between force and deformation but unloads back along the samepath 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 betweenimpacting structures.

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

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

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 afunction 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 structure’s 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 term ination 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 step2 -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 iand 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.

iThe 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] givesT

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

iDividing through by M the second order ordinary differential equation is obtained for each mode i as*

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

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

iIn a modal Response Spectrum analysis the Base Shear V in the ith mode of a structure can be obtained from

Athe Spectral Acceleration S [Carr 1994] using the following equation.

The Effective W eight 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 W eights 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 2where {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.

W hen 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

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

Twhere 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

gwhere {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 gGiven the ground acceleration u( (t) this will have to be integrated with respect to time to give u0 (t) and u (t). If

gthe 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

gW e 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 optim ises 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

W hen 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 2beam 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 mLetting : , : , : , : , 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 Twhere 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 SW here [C ] and [K ] are the secant damping and stiffness matrices. i.e.

Inertia Damping Elasticwhere 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 W en, Y. Random Vibration of Hysteretic Degrading Systems. J. Eng. Mech. Div., ASCE,

V107, No. EM6, Dec.1981, pp 1069–1087.

Banon, H. and Veneziano, D. Seismic Safety of Reinforced Concrete Members and Structures. Earthquake

Engineering and Structural Dynamics, Vol. 10, 1982, pp179–193.

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-89–0033, 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. 9–13, 1997, Vol. 1, pp 42–48.

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, 21–23 June 1993, Moan, T. et al, Eds. Balkema, 1993, pp 169–176.

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

pp 129–146.

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 221–228.

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 269–271.

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 855–868.

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 705–721.

Cook, R.D. Remarks About Diagonal Mass Matrices. Int. J. Numerical Methods in Engineering, Vol. 17, 1981,

pp 1427–1449.

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 253–274.

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 433–445.

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

pp 1629–1653, 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, W airakei, 18–20 March 1994, pp 96–101.

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 431–478.

Kaldjian, M.J. Moment-Curvature of Beams as Ramberg-Osgood Functions. J. Struct. Div. ASCE, Vol. 93,

No.ST5, Oct. 1967, pp 53–65.

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, W ellington, NZ., May

1983.

Kent, D.C. and Park, R. Flexural Members with Confined Concrete. Journal of the Structural Division, ASCE.

Vol. 97, No. ST7, July 1971, pp 1969–1990.

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 233–243.

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 289–324.

Krawinkler, H. and Zohrei, M. Cumulative Damage in Steel Structure Subjected to Earthquake Ground

Motions. Computers and Structures, Vol. 16, No. 1–4, 1983, pp 531–541.

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 587–588.

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 399–421.

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 333–344.

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 125–159.

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 203–239.

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 929–950.

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 722–757.

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 249–267.

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.

42–67.

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 W alpole, 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 W alpole, W .R. Analytical Prediction of Seismic Behaviour for Concentrically-Braced

Steel Systems, Earthquake Engineering and Structural. Dynamics, Vol. 26, 1997, pp 859–874.

Remennikov, A.M. and W alpole, 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 349–355.

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 429–457.

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. W airakei, 27–29 Mar,

1998, pp 75–82.

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.

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

April 1976, pp 249–263.

W idodo. The Rocking of Multi-storey Buildings. Ph.D Thesis, Department of Civil Engineering, University of

Canterbury, February 1995, 400p.

W ilson. E. L. and Dovey. H. H. Solution or Reduction of Equilibrium Equations for Large Complex Structural

Systems. Advances in Engineering Software, Vol. 1, No. 1, 1978, pp 19–25.

71

W ilson, E.L. and Penzien, J. Evaluation of Orthogonal Damping Matrices, Int. J. Numerical Methods in Engg.,

Vol. 4, 1972, pp 5–10,

W olf, 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 575–580.

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 m inus 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 W hen 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 W hen 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 W indows 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. W hen 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

Lwhere 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 W indows 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 W RITE 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 m eans 6 integers 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. W ith 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.

W hen 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 W ork Dissipated

FT(10) = Strain Energy

FT(11) = Applied W ork Done

FT(12) = Plastic W ork (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 W ork Dissipated

FT(13) = Strain Energy

FT(14) = Applied W ork Done

FT(15) = Plastic W ork (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 W alls

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 W inkler 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 W inkler 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