SPEED
User guide

Table of Contents

A SPEEDy user's guide

The following file are mandatory inputs for SPEED:

  • SPEED.input: Header File
  • FileName.mesh: Mesh File
  • FileName.mate: Material File

  • LS.input: Monitors File

    Other secondary files, which may be needed or not, according to the simulation, are:

  • ALL.out: Mesh file containing the geometry of the topography (not-honoring approach)
  • XYZ.out: Mesh file containing the geometry of the alluvial basin (not-honoring approach)
  • VS_RS.out: Input file for vs30 and sediment thickness (enhanced not-honoring approach)
  • MLST.input: File containing infos about monitored points
  • FACES.input: File containing infos about DG interface conditions
  • DGFS.input: File containing infos about DG interface conditions

All input files are ASCII text files. Command lines are not ordered, nor structured. A command line is identified by a 7/8 characters keyword, starting the line. If a line does not start with a recognized sequence of characters is considered a comment. That is, a space at the beginning of a line identifies that line as a comment. No other specific syntax for the comments is given and only minor syntax check is provided at the moment.

SPEED.input

The header file SPEED.input fixes the fundamental parameters of the analysis. Here follows a list of admissible keywords:

  • GRIDFILE FILENAME
    • FILENAME.mesh contains the description of the mesh (see Mesh File)
  • MATFILE FILENAME
    • FILENAME.mate contains the description of the material properties, interface and boundary conditions and external source terms (see Material File)
  • MPIFILE DIRNAME
    • DIRNAME: Name of the directory in which you want to store files *.mpi during the execution of SPEED. If absent files *.mpi will be stored in the working directory.
      Note
      If the keyword is present, then the folder DIRNAME must be created in the working directory before running SPEED.
  • MONFILE DIRNAME
    • DIRNAME: Name of the directory in which you want to store files MONITOR*.* during the execution of SPEED. If absent files MONITOR.* will be stored in the working directory.
      Note
      If the keyword is present, then the folder DIRNAME must be created in the working directory before running SPEED.
  • BKPFILE DIRNAME
    • DIRNAME: Name of the directory in which you want to store files backup files *.out (for the restart) during the execution of SPEED. If absent files *.out will be stored in the working directory. See RESTART keyword below
      Note
      If the keyword is present, then the folder DIRNAME must be created in the working directory before running SPEED.
  • DAMPING VAL
    • Set VAL=1 for frequency proportional damping or VAL=2 for frequency constant damping
  • DGMETHOD VAL
    • Select the DG method used, in particular: VAL 1 -> NIP, VAL 0 -> IIP, VAL -1 -> SIP (recommendable)
  • PENALIZC VAL
    • VAL: Penalty value for DG approximations. VAL > 100 is recommended to prevent numerical instability.
  • STARTIME T0
    • T0: Initial time for the simulation. Default T0 = 0.
  • STOPTIME TF
    • TF: Final time for the simulation.
  • TIMESTEP DELTAT
    • DELTAT: Time integration step adopted.
  • TIMEFIXE DELTAT_FIX
    • DELTAT_FIX: yes or not. A priori fixed (yes) or computed through CFL condition (not) time integration step.
  • TMONITOR TMON
    • Write output results at times t* multiple of TMON*TIMESTEP.
  • TESTMODE TEST
    • Use this keyword with TEST=1, for creating a test case for which the analytical solution is known.
  • TIMERR TERR
    • TERR is the instant of time in which you want to compute the error between the approximated solution and the analytical one. Use this keyword with TESTMODE.
  • RESTART NTS
    • NTS is Number of time steps before saving again BKP_FILES. Suppose that you want to run a simulation between 0 and 10 sec with 10000 time steps and you use the lines:
      • STARTIME 0
      • STOPTIME 10
      • RESTART 10000
        Next, you restart from 10 sec and arrive to 20 second of simulations, by using the lines
      • STARTIME 10
      • STOPTIME 20
      • RESTART 10000
  • OPTIOUT DIS VEL ACC STRESS STRAIN ROT FORMAT DATA
    • Options for the output
    • DIS: 1(0) save (do not save) the displacement field
    • VEL: 1(0) save (do not save) the velocity field
    • ACC: 1(0) save (do not save) the acceleration field
    • STRESS: 1(0) save (do not save) the stress tensor
    • STRAIN: 1(0) save (do not save) the strain tensor
    • ROT: 1(0) save (do not save) the rotational tensor
    • FORMAT: DUMMY
    • DATA: DUMMY
  • MLST DEPTH VAL
    • DEPTH: Starting depth for monitored point search
    • VAL: 1(0) Read(Write) MLST.input in the working directory

Mesh File

The file FileName.mesh contains the mesh of the computational domain. To see how generating a mesh with CUBIT software see Input files generation. Mesh files must be written in the following format

First  line:          total_number_of_nodes     total_number_of_elements      0     0     0
Second line:          ID_node     X      Y    Z
Third  line:          ID_node     X      Y    Z
Fourth line:          ID_node     X      Y    Z
.....
.....
.....
(following):          ID_element     #block       element_type       connectivity
.....
.....
.....

Material File

The file FileName.mate contains the description of the parameters of the problem including polynomial approximation degrees, boundary conditions and external loads. Here follows a list of admissible keywords:

  • MATE BLOCKID DEGREE RHO VS VP QS QP
    • BLOCKID: Id for the material, defined and exported from the mesh generator.
    • DEGREE: Polynomial degree adopted for the material
    • RHO: Mass density
    • VS: Shear wave velocity
    • VP: Compressional wave velocity
    • QS: Quality factor for shear waves
    • QP: Quality factor for compressional waves
  • MATN BLOCKID DEGREE NF DEPTH
    • Assigns non linear elastic properties to a group (BLOCKID) of elements.
    • BLOCKID: block number defined and exported from the mesh generator
    • DEGREE: polynomial approximation degree used in the subdomain with label BLOCKID.
    • NF: number of function associated to BLOCKID
    • DEPTH: depth (with respect to the topography) of the non linear layer.
  • ABSO FACEID
    • FACEID: Id for the block, defined and exported from the mesh generator. Absorbing boundary conditions are applied to faces of hexahedral elements.
  • DGIC FACEID VAL
    • FACEID: Id for the block, defined and exported from the mesh generator for DG interfaces.
    • VAL: 1(0) Project(Receive) quadrature nodes when DG interface conditions are applied to faces of hexahedral elements.
  • CASE NCASE BLOCKID TOL
    • Assign material properties node by node through a not-honoring strategy. It needs the input files ALL.out and XYZ.out.
    • NCASE: Id number for particular scenario considered (defined inside MAKE_ELTENSOR4CASES.f90)
    • BLOCKID: Id for the block where the not-honoring strategy is applied
    • TOL: tolerance for the definition of not-honoring interfaces.
  • FMAX FREQ
    • FREQ: For damping type = 1 is the frequency value used for computing the QS factor. If not assigned is assumed to be equal to 3.
  • FUNC NF TYPE PARAMETERS
    • Defines a function of time, used to scale applied loads and boundary conditions. Different formulations and function types are possible and are specified with the second number in the syntax.
    • NF: Id number of the function used for distinguish different functions
    • TYPE:
      • 0 Unit Constant Load
      • 1 Ricker "beta" type wavelet
        Parameters: beta t0
        • f(t) = (1 - 2*beta*(t-t0)^2))*exp(-beta*(t-t0)^2)
      • 2 Ricker "cos" type wavelet
        Parameters: beta t0
        • f(t) = cos(pi*beta*(t-t0))*exp(-0.5*beta^2*(t-t0)^2)
      • 3 Time function of (Nt,Ft) given values written in FileName
        Parameters: Nt FileName
        FileName must be formatted in the following form
        Nt
        0 val0
        t1 val1
        ...
        T valn
      • 4 First derivative of Ricker wavelet
        Parameters: beta t0
        • f(t) = 2*beta*(t-t0)*(-3 + 2*beta*(t-t0)^2)*exp(-beta*(t-t0))
      • 5 First derivative of Gaussian wavelet (Can not be associated to SISM command) Paramters: fp t0
        • f(t) = 2*pi*fp*sqrt(exp(1))*(t-t0)*exp(-2*(pi*fp)^2*(t-t0)^2)
      • 6 Ricker "beta" type wavelet
        Parameters: beta t0
        • f(t) = (2*pi*beta*(t-t0))*exp(-2*pi^2*beta^2*(t-t0)^2)
      • 7 Gaussian function (Can not be associated to SISM command) Parameters: beta t0
        • f(t) = (6*beta-24*beta^2*(t-t0)^2 + 8*beta^3*(t-t0)^4) * exp(-*beta*(t-t0)^2)
      • 8 Cosine function (Can not be associated to SISM command) Parameters: fp
        • f(t) = cos(fp*2*pi*t)
      • 9 Sine function (Can not be associated to SISM command) Parameters: fp
        • f(t) = sin(fp*2*pi*t)
      • 12 Smoothed ramp source: (Can not be associated to SISM command) Parameters: amp, a, c
        • f(t) = amp*(1/(1+exp(-a*(t-c))))
      • 13 Grenoble benchmark Parameters: tau, amp
        • f(t) = 0.5*(1 + erf(amp*(t - 2*tau)/(tau/2)))
      • 14 SCEC benchmark Parameters: tau, amp
        • f(t) = 0 for t < 0
        • f(t) = 0 for t = 0
        • f(t) = amp*(1-(1 + t/(tau*0.25))*exp(-t/(tau*0.25)))
      • 15 Explosion (Can not be associated to SISM command) Parameters: ps0, tplus, alpha, t0
        • f(t) = ps0 * (1 - (1 + (t-t0)/tplus)*exp(-alpha*(t-t0)/tplus))
      • 31 Time function of (Nt,Ft) given values written in FileName (Available only for SISM comand where Rise time, Rupture Time and Moment tensor are defined)
        Input Source Time function using Text File. Supplied Input Time series file. Sufficient to just define the Unit Value Function
        • Function Value = Value_from_time_Series*Moment_tensor_component. Starting Time in Time series is 0sec. End Time is Rise Time. At the end of the Rise time, Value_from_time_Series = 1; (Unit Slip)
      • 32 Ramp Slip-Time Function (Available only for SISM comand)
        • f(t) = 0 for t < t_rupt
        • f(t) = 1 for t > t_rise + t_rupt
        • f(t) = (t-t_rupt)/t_rise otherwise
      • 33 Time function of (Nt,Ft) given values written in FileName (Available only for SISM comand)
        . Same as FUNC 31 but with scaled Rise time.
      • 50 Grenoble benchmark 2 (Available only for SISM comand)
      • 60 Function for G/G0 (linear equivalent option, contact developers)
      • 61 Function for damping (linear equivalent option, contact developers)
      • 99 Cashima Benchmark Parameters: tau, amp
        • f(t) = exp(-(((4*asin(1))*1.5)*(t-tau)/amp)^2)
          *cos(((4*asin(1))*1.5)*(t-tau)+2*asin(1)/2)
      • 101 f(f) = t
  • SLIP SRCNAME
    • Use SRCNAME = LOAD-SRCMOD2 to use the finite fault rupture generation
  • NHEE TOL
    • TOL is the tolerance for finding nearest grid points with respect the Not-Honoring Enhanced Approach (material properties given by cloud-points, see the Croissant valley tutorial)
  • SISM NF DUMMY XIPO YIPO ZIPO X1 Y1 Z1 S1 S2 S3 N1 N2 N3 R M T
    • Assign seismic moment. Fault plane is discretized by double couple point sources. For each of them the load is specified with a specific "SISM" instruction. These lines can be generated by the ThreePTool in ThreePTool. One SISM line represents one double-couple point source.
      • NF : Number of time function associated with the load (see FUNC keyword)
      • DUMMY : Dummy input
      • XIPO, YIPO, ZIPO: Coordinates of ipocenter
      • X1,Y1,Z1: Coordinates of the point source
      • S1,S2,S3: Cosine director of the slip vector
      • N1,N2,N3: Cosine director of the normal vector
      • R: Rupture time
      • M: Value of the seismic moment applied to the point
      • T: Rise time
  • PLAX NF BLOCKID VAL
  • PLAY NF BLOCKID VAL
  • PLAZ NF BLOCKID VAL
    • Defines a plane wave source. This is realized introducing a force time history, able to generate a displacement time history with the Ricker wavelet shape (NF = 4), on a certain surface. The load along the X, Y or Z direction is specified as the product of a time function of index NF, times a point load of intensity VAL integrated on the element.
    • NF: number of function associated with this load (see FUNC keyword)
    • BLOCKID: block id number defined and exported from the mesh generator
    • VAL: value of the applied load
  • NEUX BLOCKID NF VAL1 VAL2 VAL3 VAL4
  • NEUY BLOCKID NF VAL1 VAL2 VAL3 VAL4
  • NEUZ BLOCKID NF VAL1 VAL2 VAL3 VAL4
  • NEUN BLOCKID NF VAL1 VAL2 VAL3 VAL4
    • Assigns Neumann boundary conditions to a group (BLOCKID) of surface (quad) elements. The load may be applied in the X, Y, Z or Normal direction. The load is specified as the product of a time function of index NF, times a distributed load varying from VAL1 to VAL4.
    • BLOCKID: block id number defined and exported from the mesh generator
    • NF: number of function associated with this load (see FUNC keyword)
    • VALi: value of Neumann load at vertex i of the element
  • DIRX BLOCKID NF VAL1 VAL2 VAL3 VAL4
  • DIRY BLOCKID NF VAL1 VAL2 VAL3 VAL4
  • DIRZ BLOCKID NF VAL1 VAL2 VAL3 VAL4
    • Assigns Dirichlet boundary conditions to a group (BLOCKID) of surface (quad) elements. The load may be applied in the X, Y or Z direction. The load is specified as the product of a time function of index nf, times a distributed load varying from VAL1 to VAL4.
    • BLOCKID: block id number defined and exported from the mesh generator
    • NF: number of function associated with this load (see FUNC keyword)
    • VALi: value of Dirichlet load at vertex i of the element
  • PLOX NF X Y Z VAL
  • PLOY NF X Y Z VAL
  • PLOZ NF X Y Z VAL
    • Assigns Neumann type point load to the spectral node nearest to a specified X,Y,Z position. The load along the X, Y or Z direction is specified as the product of a time function of index NF, times a point load of intensity VAL.
    • NF: number of function associated with this load (see FUNC keyword)
    • X Y Z: coordinates of the desired point of application
    • VAL: value of the applied load
  • FORX NF X Y Z VAL
  • FORY NF X Y Z VAL
  • FORZ NF X Y Z VAL
    • Assigns a force (volume) load along the X, Y or Z direction.
    • NF: number of function associated with this load (see FUNC keyword)
    • X Y Z: coordinates of the desired point of application
    • VAL: value of the applied load
  • TEST NF
    • NF: number of function used in the TESTMODE case.

Monitors File

The file LS.input contains a list of monitored points for which the solution is written in output.

The list of monitored points must be written in the following format: 

#Monitors
1 X Y Z
2 X Y Z
3 X Y Z
.....
.....
.....
#Monitors X Y Z
Note
To generate a long monitors list see Input files generation.