SAP IV

1. Introduction

The finite-element package SAP IV was originally developed in the 1970’s at UC Berkeley and was freely distributed in source form. I have modified it somewhat here over the years. The official source code (as modified for various platforms at various times by various people) and documentation are currently available from NISEE at UC Berkeley; download requires membership in The Earthquake Engineering Online Archive (US$25/year) and the software and documentation ‘may not be used for commercial purposes or redistributed in any form’. Other software from NISEE includes NONSAP and PC FEAP.

We have also developed Saq, a programme for running Sap with queries. It uses Fad to modify the .sap model-definition file in response to user input, generates a new .sap file with a unique name, and submits one or more simulation runs as a background job.

2. Installation

We are using Sap under Debian GNU/Linux.

2.1 GNU/Linux

Sap and Saq for 64-bit GNU/Linux can be downloaded here:

• sap (amd64/x86_64 binary)
• saq (amd64/x86_64 binary)

3. Local documentation

We have created an HTML version (restricted access) of the original printed User's Manual (Bathe, Wilson and Peterson, 1974) for internal use only.

The original scanning and OCR were done by Mathieu Dessain (1993 July/August), based on which Robert Funnell (1997 Jan) created a primitive set of HTML pages. Shervin Talebi (1998 Jul/Aug) enhanced the HTML and added some navigation links. Kailesh Mussai (2000 Jun) enhanced it further (including scanning missing pages, and adding images for figures and equations). Since then, Robert Funnell has made various changes.

We have also created some incomplete documentation of internals (restricted access).

4. Usage tips

4.1 Running Sap directly

Sap is run from the command line.

If you run Sap directly it will display a prompt for the name of the .sap input file:

Sap will then display two prompts:

Scale factors (Jacobi, Brick8)? Constraint coefficient?

Normally you should just type Enter for both of these. You may then see a warning errset not yet implemented ... which can be ignored.

Sap will hopefully now run.

(The scale factors for Jacobi and Brick8 are used to avoid numerical problems in certain cases. Their default values are 1.0, which should usually be fine. The constraint coefficient, if non-zero, is used to constrain an unsupported structure; it is not required for any physically reasonable model.)

4.2 Running Sap using Saq

The Saq programme is the recommended way of running Sap under GNU/Linux. (It doesn't yet work under Microsoft Windows.) Saq queries the user about what is wanted, generates a new .sap file with a unique name, and submits a background job.

Like Sap, Saq is run from the command line. Normally you would cd to the directory where the .sap file is. If the name of the model-definition file is modelname.sap, then give the command

(For all queries, respond with the requested information followed by the Return or Enter key.)

Saq will then ask what type of simulation is desired:

• Static - Static problem
• Eigen - Eigenvalue/eigenvector problem (for natural frequencies and mode shapes)
• Direct - Direct step-by-step time-domain response (also used for computing frequency responses)

Saq then asks whether you want to run Fad, to make various other changes to the model. Answer with Y or N. (In the current version of Saq, if you answer No then the model-definition file will not be modified to reflect your requested simulation type.)

Saq will then allow you to modify various model parameters, depending on which simulation type you've selected.

4.2.1 Static case

Saq will allow you to specify the use of either pressures (assumed to already be defined in the model) or concentrated loads (always applied in the z direction, and assuming that none are yet defined in the model). If you specify concentrated loads, Saq will repeatedly ask you for the node numbers at which the loads should be applied; just press the Return or Enter key to indicate that you've finished entering nodes. A concentrated load consisting of a force of 1. in the z direction will be applied at each node that you specify.

4.2.2 Eigenvalue case

Saq will ask you how many eigenvalues you wish to solve for.

4.2.3 Direct time-domain case

Saq will ask you for the following:

• The α and β damping coefficients
• The total time to be simulated and the time step to use
• Whether pressure or concentrated-force loads are to be used. The specification of a pressure or of concentrated-force loads is similar to that in the static case, except that at each node-number query you can specify a range of node numbers by specifying i_min and i_max separated by commas.
• Which material type(s) you wish to record displacements for

4.2.4 All cases

Saq will ask you for the number of equations/block, and whether to print out the equation numbers. These are both for debugging purposes. Normally just press the Return or Enter key for each question.

Saq creates a new model-definition file with a new name using the date and a sequence number. The new name is of the form oldname_yyyymmdd_nn. This makes it easier to keep track of results from multiple simulation runs based on the same model with different parameters.

Finally Saq will ask you if you want to actually run Sap for this model and the specified parameters. Answer Y or N.

Saq then loops back and asks again for a simulation type. If you specify something, it will again allow you to modify the parameters and submit another simulation run for the same basic model. If you don't specify a simulation type, it will ask you for the name of another model. If you specify something, it will continue by asking for a simulation type and other parameters. If you don't specify a model name, it will submit a job to be run in the background, consisting of all of the model modifications and simulations that you have requested. When the job finishes an e-mail message will be sent to you at your local username.

4.3 Postprocessing

Sap should produce a .res file as output, as well as a number of other working files. If the run was successful, the .res file should contain a listing of the input model specifications followed by some results, and should end with information about the execution time, e.g.,

      S T A T I C   S O L U T I O N   T I M E   L O G
     
	  EQUATION SOLUTION   =    1.22
	  DISPLACEMENT OUTPUT =    0.07
	  STRESS RECOVERY     =    0.34
     
      O V E R A L L   T I M E   L O G
     
	  NODAL POINT INPUT            =      0.11
	  ELEMENT STIFFNESS FORMATION  =      1.61
	  NODAL LOAD INPUT             =      0.01
	  TOTAL STIFFNESS FORMATION    =      0.68
	  STATIC ANALYSIS              =      1.65
	  EIGENVALUE EXTRACTION        =      0.00
	  FORCED RESPONSE ANALYSIS     =      0.00
	  RESPONSE SPECTRUM ANALYSIS   =      0.00
	  STEP-BY-STEP INTEGRATION     =      0.00
     
	  TOTAL SOLUTION TIME          =      4.05

5. Local modifications

Since 1976 I have ported SAP IV to various hardware and operating systems, including RSX-11M, VAX VMS, Digital Unix, Debian GNU/Linux and Microsoft Windows.

The following is a brief list of local modifications to SAP IV, in approximate decreasing order of importance. (Names in curly brackets {} are subroutine names.)

• Input file format
  • Require an asterisk at the beginning of the heading card, to allow for multiple heading cards (used for recording a history of model revisions)
  • Suppressed use of 1st column for indicating cylindrical coordinates, to allow > 9999 nodes {inputj}. The original input list and format for nodes were

    IT,N,JPR,(ID(N,I),I=1,6),X(N),Y(N),Z(N),KN,T(N)
    (2(A1,I4),5I5,3F10.0,I5,F10.0)
    	  

    Now (version 2), forcing Cartesian and not permitting Cylindrical, the input list and format are

    N,JPR,(ID(N,I),I=1,6),X(N),Y(N),Z(N),KN,T(N)
    (I5,(A1,I4),5I5,3F10.0,I5,F10.0)
    IT=' '
    	  

    However, if there’s a line after the master control line that says nodes_v3, then (version 3) the input list and format are

    IT,JPR,N,(ID(N,I),I=1,6),X(N),Y(N),Z(N),KN,T(N)
    (2A1,7I5,3F15.0,I5,F10.0)
    	  

  • Accommodate new element features for pre- and post-processing (plotting levels, colours) for some element types (including shells and tetrahedra). The input formats for truss and pipe elements are unchanged.
• Added tetrahedral element (type 13)
• Changed handling of shell triangles to facilitate anisotropy {qdcos}
• Implemented master and slave nodes for shell elements {shslav}
• Added code for constraining an unsupported structure {addstf, secntd, sspceb}
• Added ability to interrupt direct-integration run after specified time (and write out final displacements, velocities and accelerations) {solstp}
• Allow for direct-integration restarts {addstf}
• Various changes to scale factors and other constants to accommodate smaller coördinates and to try to reduce underflows and overflows {addstf, bandet, jacobi}; various playing with run-time error checking
• Converted from REAL*8 to REAL*4 in 1976 when memory was very tight, then in 1985 converted back to REAL*8 (involved name changes for some intrinsic functions)
• Adjustments to improve variable alignment in commons
• Separated some code into setup.for and setupf.for
• Separated some declarations into files sap.dcl and sapfn.dcl, and use of INCLUDE
• Replaced dummy dimensions '1' by '*' to improve error checking
• Fixed apparent bug in array declaration, and apparent typo in do-loop variable {st8r21}
• Renamed intrinsic function DARSIN to DASIN {benddc}
• Cleaned up some laxity in handling of things in commons {brick8, lststr, slcct, slst}
• Minor changes to file handling, including
  • start with logical unit 5 pointing to interactive terminal for specifying scale factors, restart, etc., then switch it to read input file
  • assigned more meaningful filenames for some working files
  • avoid overwriting mass file
  • additional status checks
  • write date into results file
• Minor changes to handling of character strings
• Implemented a file mark/point mechanism to replace slow backspaces operations (used this from 1983 to 1993, is no longer necessary)
• Did a lot of fiddling around, including breaking up some subroutines and designing elaborate overlay structures, to squeeze code into small amounts of memory under RSX-11M
• Various minor fiddling for debugging, commenting, etc.