Chapter 4

BUILDING INPUT FILES

All Coulomb calculations require input files; some require successive information for which you will be prompted. If an input file is improperly-formatted (e.g., it has tabs, or the number of faults is inconsistent with the ‘#fixed=’, a warning dialog will appear. If it is a text (.inp) file, you must modify the input using text editor. If it is a binary (.mat) file you cannot use it. You can also create an input file interactively or modify an existing file in Coulomb. Open this input file in a text editor:

All numbers need a decimal point, except for the line starting “#reg1=” and the first three characters of the source parameters marked ‘#’. All format statements are shown at the end of this chapter. Right-lateral and reverse slip are reckoned positive (negative values denote left-lateral and normal slip); dip must always be positive. “#reg2=” is an obsolete inheritance from Coulomb 1.0; ignore it.

There is an alternate ‘rake’ input format that specifies rake (°) and net slip (m). This permits one to calculate the stress change on receivers (faults without slip) in their rake directions, where for example, a left-lat. stress increase would inhibit failure on a right-lateral fault. Try Input > Open & edit input file > ‘Example-2(LL)rake.inp’ to see this:

4.1 Structure and format for input files

An input file is composed of parameters for the halfspace, regional stress field, source fault positions and slip, receiver fault positions, grid information, graphical representation, and optional cross section and lat/lon information. See the figure, ‘Structure and formats of Input file’, which annotates the entries. The numbers should be filled within the designated areas with appropriate values. When making or modifying input files, use a non-kerning (uniform-spacing) font, such as Monaco, so that all numbers align under the xxxxxxxx headers.

4.2 Working in lat/lon coordinates

Coulomb can read and display lat/lon’s if you include the lat/lon of the grid borders and the (0, 0 km) point in the input file, as seen here from ‘Example-SFBayArea.inp’

If you have lat/lon information for a source, you can convert it to Coulomb (x, y) input format by selecting Functions > Tools > Convert lat/lon to Cartesian, which brings up a calculator window.

4.3 To open, display and modify existing input file interactively

Input > Open existing input file > Example-2(LL)-lonlat.inp in the “input_files” sub-folder within the “Coulomb 3.1” folder.

The graphic on the left below appears in the Coulomb 3.1 window. You can see the undistorted grid (yellow) and the surface projection of the source fault (green).

To show the same plot with lat/lon tic marks, put the cursor on the frame numbers and make a right mouse-click (above right). Choose change coordinates and make a leftmouse-click. Alternatively, from the menu, Input > Preferences and change Coordinates from Cartesian to Lon. & Lat., and click OK.

To modify a source or receiver fault, click on the fault with the right mouse click, and it will open the ‘change fault params’ window (below left). You can do the same thing to the blue study area border to change the study area boundaries.

4.4 To display the undistorted grid in 3D view

1. Choose Functions > Grid > 3D view. The graphic above right appears in the Coulomb 3.1 window. You can see the undistorted grid in 3D view (yellow) and the fault patches colored by their input slip. You can examine the slip components, change the viewing angle numerically, or with the rotate tool to the right of the ‘hand’ icon.

4.5 Modifying an existing file in a text editor

Click one of the example files we prepared for tutorials.

To duplicate it, type ‘d’ holding command key (command + D), or drag the icon holding option key.

Rename it.

Launch an editor and open the file using File > Open (command + O).

Use a non-kerning (uniform-spaced) font, such as Monaco or Courier. Change the numbers you want, checking the units and format. If you want to add source or receiver faults, you can add a new row. Make sure that the number of the rows (faults) and the number of the fixed faults (#fixed= ) in the third row in the input file are the same. Some of the editors have an option to ‘show invisibles’. If your editor has the function, make sure that your modified numbers are filled in the properly formatted areas and there are no tabs. A tab will crash the program.

Save the file.

4.6 Editing existing input files within Coulomb (no need to worry about formats)

If you already have an input file prepared, after launching the program the file is read by choosing Input > Open & Edit Input File. The “input_window” will appear as shown below. You can modify values in the boxes of elastic parameters, regional stress settings (only used for ‘Opt.-‘ stress calculations), Study area (grid), and Fault Data. If the ‘Total number of faults’ is greater than 1, enter the order number of a specific fault patch that you wish to modify below “#”. Then click “OK”, properties of that particular source will appear.

4.7 Building an input file from a simple X,Y map

To build an input file from map, you can select from menu Input > Build Input File from x & y Map. You can add Longitude and Latitude information of your study area by clicking the Add lon.lat. info button”. We explain how the regional stress is used in Chapter 7, so don’t worry about it now.

Note that you must close the above warning message before specifying a fault on the following map. Click “OK” and the fault color will turn to green.

4.8 Tapering the slip on a source fault

To remove unrealistic stress concentrations at the edges of a fault, you can taper the slip automatically in Coulomb. Choose Input > Open an existing file and choose ‘Example-2(TH).inp’. Then choose Functions > Tools > Taper or subdivide fault slip. When the Element input panel appears, choose ‘Linear tapering’. The tapered slip is built by nested rectangles. Choose 10 km along strike, 5 km down-dip, and 5 nested patches, and hit OK. Save the tapered input file by Input > Save input file as ascii with a new name, and open it in an editor to see the 5 nested coplanar sources, as shown below.

Notice that the patches get successively smaller on down the list, and that each patch has the same slip. The seismic moment (summed slip x area of each patch) of the tapered source is identical to that of the original uniform-slip input file. The larger the number of patches, the smoother the stress but the longer Coulomb needs to calculate.

Tapered slip (use for sources only) Subdivided slip (for sources and receivers)

4.9 The seismic moment is calculated every time an input file is loaded

Every time you launch an input file, it calculates the total seismic moment of the sources in the input file, using the fault area, slip, Young’s modulus, E, and Poisson’s ratio, PR, from the input file. The seismic moment (in dyne-cm) and the equivalent M_w appears in the Matlab window:

So, if you want to the seismic moment of individual sources, remove the others from the input file. The tapered fault will always have the same moment as its untapered version.

4.10 Sub-dividing or ‘tiling’ the slip on a fault

Many large sources have variable slip models with numerous small patches of slip. You might also want to subdivide a receiver fault so that you can assess the variations in stress imparted by a nearby earthquake.

The simplest method is simply to change the number beneath the # in the input file from 1 (for 1 patch) to a large number (for the number of patches). See p. 14 for a graphic). The ‘# fixed’ sources in the third line of the input file is unchanged.

As you did before, choose Input > Open an existing file and choose ‘Example-2(TH).inp’. Then choose Functions > Tools > Taper or subdivide fault slip. This time, when the Element input panel appears, click on ‘Splitting’. Now choose a 7 x 3 patch subdivision, and hit OK, and you will see the picture above right. Save the tiled input file by Input > Save input file as ascii with a new name, and open it in an editor to see the 21 adjacent coplanar sources, all with the same slip as the initial input file. You can now change the slip on each patch by hand. The input folder contains two examples of these (the 1992 M=7.3 Landers, California, and 1995 M=6.9 Kobe, Japan, shocks).

If you are tapering or subdividing a vertical fault, you can still see the nested or tiled patches by choosing Functions > Grid > 3D view. Then you can use the swivel tool to view it on its side. 3D view is also valuable because the patches are colored by their slip, rather than being translucent. Notice the rake vectors with tiny arrow heads.

Subdivided fault in 3D view Use swivel tool in menu

4.11 Making realistically-scaled source faults from CMT or focal mechanism data

1. Choose Input > Build input file from lon. & lat. map. The Map positions to Cartesian positions calculator will appear:

2. Press 'Calc.' in the 'Study area' box (above) to calculate boundaries and grid increments of the study area (the yellow fields). Then hit 'Add to map' to apply changes to Coulomb window, which will create the grid.

3. To create the source fault from the CMT information, drop down to the 'Fault element' box (above left). You can choose the ‘Fault center’ (this is the geometrical center of the rectangle, so make sure the top of the fault is at or below the ground surface), or the ‘Start-point per Aki-Richards' (this is the Coulomb start-x, start-y position), and then input the M_w, strike, dip, and rake from a CMT file. In this example, just change M_w to 6.8 and change the dip to 20°.

4. If you would like to use empirical magnitude-area relations to estimate appropriate fault lengths and widths, press the ‘From empirical relations' button, and the 'empirical relations…' box will appear (above right). Choose the type of fault (here, reverse) and hit ‘Calc.’ To accept the length and width values, hit the 'Apply' button, and then close the 'empirical relations’ window. You will see 'length' and 'width' information changed in the Fault elements box. Notice, however, that these relations permit the fault width in large strike-slip events to get too deep.

Now press 'Calc.' in the Fault element window to calculate fault position, and press 'Add to map' to apply the fault to the coulomb window. A portion of the resulting map is shown above at right. Notice that the blue dot is the fault reference point you selected. To save the input file you just created, choose ‘Save input file as ascii’ in the Input menu, and name it. You can replace the comment lines to the file.

If you would like to add more sources, after you have hit, ‘4) Add to Map’, just increment the ‘ID number’ to 2 and put in the new values into the ‘Fault elements’ window.

4.12 Converting online variable-slip coseismic models to Coulomb input files

Martin Mai (ETH Zurich) has built the outstanding SRCMOD database of over 150 variable-slip input files from the literature, which can be read in as Coulomb input files. Bear in mind that these files can have hundreds to thousands of slip patches are so calculations, particularly ‘3D view’ and ‘calc. slip on faults’, can be very slow.

1. Go to http://www.seismo.ethz.ch/srcmod/ and click on ‘Downloads’. Then download the most recent .mat file for Matlab 7 (the top file below left) to the Coulomb30 folder. Make sure you Save as a binary ‘.mat’ file, not a ‘.txt’ file.

2. In the Matlab command window, type the plugin ‘srcmod2coulomb’. You will then see the file selection window (above right). The selected file will automatically be saved into the input file folder as an .mat input file. The file name will also indicate the number of sources (‘_100f_’ means 100 slip patches). Warning: A large number of patches demands much more calculation time.
3. Then, Input > Open existing input file > Grid >3D view. The example below left is ‘s1987WHITTIhart_100f_coulomb.mat’, the 1987 M_w=6 Whittier Narrows shock:

4.13 Merging several variable-slip models to one input file (‘merge_input_files’ plugin)

Sometimes you will want to take many variable-slip input files for nearby earthquakes and merge them into one .mat input file. Here’s how you do it:

1. Open an existing input file. Type ‘merge_input_file’ into the Matlab command window. You are then requested to choose the second input file. This process is repeated until you have included all files that you want.
2. Save the combined file with any name you would like. In the example above right, we used the Overlay > Annotation tool to add the quake names to the map. They will be preserved in the .mat file, although you need to uncheck and recheck them when you next plot the file (a Matlab bug).