An introduction to the Blocks software packageBrendan J. Meade1 and John P. Loveless2

1. meade@fas.harvard.edu, Department of Earth & Planetary Sciences, Harvard University2. loveless@eps.harvard.edu, Department of Earth & Planetary Sciences, Harvard University

1

IntroductionThis document provides a brief introduction to using the Blocks software package to interpret both geodetic and

geologic kinematic data at plate boundary zones. The complete theory behind the core algorithms is described inMeadeandLoveless"Block modeling with multiple fault network geometries and a linear elastic coupling estimatorin spherical coordinates", Bulletin of the Seismological Society of America, December 2009. The purpose of thisdocument is to provide a concise overview of how to use Blocks in terms of building the files necessary for amodel to run. The software is written in Matlab3 and requires the Mapping Toolbox4 in addition to the core Matlabengine5 (versions 2007a onward). Portions of the code benefit from using the Matlab Parallel Computing Toolbox.Downloads and updates are posted on the software page of the Crustal Dynamics group at Harvard University6.

InstallationBlocks installs just like any other set of Matlab scripts or toolbox. Once downloaded, just unzip and move the

expanded directory (along with subdirectories) to your favorite location for storing scripts. Once you've decidedon a home for these scripts (e.g., /matbin ) just add the paths to using the command "addpath(genpath(/matbin/ Blocks)); ". Simply add this line to your startup.m file to have access to Blocks every time you startMatlab. To make sure the path has been picked up correctly test the to see if you can find one of the basic functions bytyping "okada_plus_op " at the Matlab command line which should spit back a message starting with somethinglike, "??? Input argument "Pr" is undefined ". This is a good thing and if you see something likethis Blocks will run fine. However if you receive an error message like, "??? Undefined function orvariable okada_plus_op " that means that the paths have been incorrectly set and that Matlab is not findingall of the Blocks functions.

Workflow overviewA basic workflow might look something like this:

1. Create project directory (e.g., ~/northpole )2. Create .segment , .block , .sta.data , .msh , and .command files3. cd to ~/northpole4. Run main Blocks routine from Matlab command line5. Read slashdot for a few minutes while code runs6. Analyze output in sub-directory create by blocks (e.g., ~/northpole/0000000001 )

The two main steps are creating the input files (.segment , .block , .msh , .sta.data , and .command ) andanalyzing the results. For every model run from a given directory (e.g., ~/northpole ) Blocks will create a newdirectory containing both the output and input. If directory 0000000001 already exists then 0000000002 iscreated, etc.

Building .segment and .block files with SegmentManagerGuiFault network geometry is stored in a .segment file. An example of a .segment file with one fault segment is

shown below

Namest_long st_lat end_long end_lat

3. http://www.mathworks.com/4. http://www.mathworks.com/products/mapping/5. http://www.mathworks.com/products/matlab/6. http://summit.fas.harvard.edu/~meade/meade/Software.html

2

lock_dep ld_sig ld_toggledip dip_sig dip_toggless_rate ss_sig ss_togds_rate ds_sig ds_togts_rate ts_sig ts_togbur_dep bd_sig bd_togfres fres_ov fres_otherpatchFile patchFileTog other3patchSlipFile patchSlipTog other6other7 other8 other9other10 other11 other12northPole_1100.671 85.001 105.500 85.00215.0 5.0 0.090.0 1.0 0.00.0 1.0 0.00.0 1.0 0.00.0 1.0 0.00.0 0.0 0.0100.0 0.0 0.01 1 0.00.0 0.0 0.00.0 0.0 0.00.0 0.0 0.0

Fault segments are listed sequentially with no delimiters between entries. The fields are:

Name- fault segment namest_long - fault segment name start point longitude (degrees)st_lat - fault segment start point latitude (degrees)end_long - fault segment end point latitude (degrees)end_lat - fault segment end point latitude (degrees)lock_dep - fault segment locking depth (km)ld_sig - fault segment locking depth uncertainty (km) - not usedld_toggle - fault segment locking depth toggle - not useddip - fault segment locking dip (degrees)dip_sig - fault segment dip uncertainty (degrees) - not useddip_toggle - fault segment locking dip toggle - not usedss_rate - fault segment strike-slip rate a priori (mm/yr)ss_sig - fault segment strike-slip rate a priori uncertainty (mm/yr)ss_tog - fault segment strike-slip rate a priori toggle (0/1)ds_rate - fault segment dip-slip rate a priori (mm/yr)ds_sig - fault segment dip-slip rate a priori uncertainty (mm/yr)ds_tog - fault segment dip-slip rate a priori toggle (0/1)ts_rate - fault segment tensile-slip rate a priori (mm/yr)ts_sig - fault segment tensile-slip rate a priori uncertainty (mm/yr)ts_tog - fault segment tensile-slip rate a priori toggle (0/1)bur_dep - fault segment burial depth (km)

3

bd_sig - fault segment burial depth uncertainty (km) - not usedbd_tog - fault segment burial depth toggle - not usedfres - deprecatedfres_ov - deprecatedfres_other - deprecatedpatchFile - an integer corresponding to the list of triangular mesh files in the .command filepatchTog - triangular patch toggle (0/1)other3 - unusedother4 - an integer corresponding to the list of triangular mesh a priori slip files inother5 - unusedother6 - unusedother7 - unusedother8 - unusedother9 - unusedother10 - unusedother11 - unusedother12 - unused

Note that the fields fres , fres_ov , and fres_other are deprecated but maintained for compatibility withblocks_sp1 . Note that the start point and end point are interchangeable so long the dip specified according to theright-hand rule.

Obviously maintaining these files by hand is challenging for geometrically complex fault networks. EnterSegmentManagerGui , a tool for reading, manipulating, and writing .segment and .block files.SegmentManagerGui is invoked from the Matlab command line as a function call with no arguments. A screenshotis shown below:

4

The basic workflow is to load a .segment file then modify/add/delete/move/extend/connect/split fault segmentsto change the fault network geometry and properties then save the resulting .segment file (typically with a newfilename). After loading the .segment file the segments will appear as blue lines in the world map. The bottom leftcorner of the interface provides basic navigation tools to zoom in and out of a particular study area. After isolatingthe study area, individual fault segments can be selected by clicking on GSelect then clicking on the fault segment ofinterest. This will turn red as you mouse over but will not be selected till you click on or near it. This will make theselected fault the focus of subsequent actions and its properties (e.g., locking depth, slip rate constraints) can be setby selecting the desired .segment field from the pull down menu below the fault segment name. The current fieldvalue will appear in the edit box to the right of the field name. To change the value simply type in the new value thenclick update directly above this edit box. The new field value is now set but will only be saved to a .segment filewhen using the .segment file save dialog. To modify the properties of multiple fault at once over a rectangular orirregular area click GSelectBox or GSelectLasso respectively. GSelectLasso can be fussy, so please be patient withit and try re-selecting if it doesn't work as expected the first time.

There are eight tools to graphically modify fault system geometry:

1. GDelete - single segment delete2. GDeleteBox - multiple segment delete within rubber band box3. GDeleteLasso - multiple segment delete within irregular polygon4. New - create new fault segment by clicking on two points (not generally used except to create the first

segment in a region)5. Extend - extend the fault network with a new fault extending from an existing fault segment endpoint or

intersection. This command in concert with connect (below) are the preferred methods for introducing newfault segments because SegmentManagerGui ensures that start/endpoint coordinates match exactly.

5

6. Connect - introduce a new fault connecting two fault intersections7. Move - move the intersection between multiple fault segments8. Split - split a fault segment in two

One of the really cool things about .segment files is that no information about which block bound a given segmentis required. This is determined algorithmically within Blocks using the unsupervised block closure and labelingalgorithm described in MeadeandLoveless(2009). However, in order to allow for the application of a priori rotationrate constraints to a given block we make use of a .block file, which provides a simple geometric method of relatingfault segments to a given block name and rotation using only two addition coordinates (interior longitude and latitude)for each block. The basic idea is that the interior coordinates give the location of a single point at any location insideof a given block. There is one of these for each block, as well as one representing the "rest of the world", locatedoutside the main block geometry (termed the "exterior block"). This is the only information necessary to relate faultssegments to bounding blocks and proves to significantly simplify the development of geometrically complex models.The basic format of a .block file, including header, is:

Nameinterior_long interior_latEuler_long Euler_long_sigEuler_lat Euler_lat_sigrotation_rate rotation_rate_sigstrain_calc apriori_toggleother other otherother other otherChino242.146 34.0720.000 1.0000.000 1.0000.000 0.0000.000 00.000 0.000 0.0000.000 0.000 0.000

Just like a .segment file the block entries in a .block file are listed sequentially with no delimiters between entries.The fields are:

Name- block nameinterior_long - longitude of a point interior to the block boundaries (degrees)interior_lat - latitude of a point interior to the block boundaries (degrees)Euler_long - a priori Euler pole longitude (degrees)Euler_long_sig - a priori Euler pole longitude uncertainty (degrees)Euler_lat - a priori Euler pole latitude (degrees)Euler_lat_sig - a priori Euler pole latitude uncertainty (degrees)rotation_rate - a priori rotation rate (degrees/Myr)rotation_rate_sig - a priori rotation rate uncertainty (degrees/Myr)strain_calc - toggle for interior homogeneous block strain (0/1)apriori_toggle - toggle for a priori Euler pole and rotation rate constraint (0/1)other - unusedother - unusedother - unused

6

other - unusedother - unusedother - unused

Also similar to a .segment file, .block files can be created and manipulated within SegmentManagerGuiwith tools that are very similar to those for manipulating a .segment file.

After saving a version of a .segment and .block file it is useful to check the validity of these files in terms of blockclosure. The File Integrity tools (CheckClosure, CheckIPs, SegChecker, ClearChecks) do just this. CheckClosurelets you know whether or not the fault system closes. In other words, this will tell you if you have a fault thatterminates internal to a block. If you do get an error of this sort click on SegChecker to run a set of checks for likelyerrors that are displayed graphically on the map. These notations can be removed from a map using ClearChecks.If the .segment file is successfully validated by CheckClosure then run CheckIPs (with a loaded .block file) tomake sure that an interior point has been correctly specified for the current .block and .segment files (i.e. themodel configuration).

SegmentManagerGui tips:1. Save often with new file names!2. Use the pull down menu under GSelectLasso of see field current segment parameter values on the map.3. With large .segment files it may take a second or two before active highlighting or the rubber band box

becomes active; please be patient and use the "update" and "back" navigation buttons if an error message isreturned to the Matlab command window.

4. Use the Display tools right above the navigation tools to add references to the map view. Here you can addfault maps (GMT's psxy format) and GPS station coordinates (.sta.data format described below).

5. Avoid creating segments with identical start/end point longitudes or latitudes (i.e. pure north-south or east-west striking).

6. CheckClosure and SegChecker are extremely useful for identifying errors in .segment files. A .segmentfile does not have to be validated by CheckClosure or SegChecker to be read in bySegmentManagerGui .

7. If you receive the error "Interior points do not uniquely define blocks!" make sure you have placed aninterior point within each block, as well as outside the fault geometry (an exterior block). For example,in the sample input file included with the code, the exterior block is located in South China and is called"Restoftheworld".

8. A useful workflow is to convert a fault map into .segment file format then use SegmentManagerGuito systematically build a valid .segment file.

Building mesh filesTriangular mesh files are only required if spatially variable coupling slip on triangular dislocation elements is to

be estimated. Presently, the program will accept mesh files generated using the open source program Gmsh7 or a.mat file containing the element nodal coordinates and a "connection matrix" that indicates which nodes comprisethe elements. If a .mat file is specified, it must contain two variables, c and v . The coordinate array c is an n-by-3array whose columns contain the longitude, latitude, and depth (in km) coordinates of the the elemental vertices.The vertex index array v is an m-by-3 array that contains the indices of the vertices that comprise each element. Forexample, if the first element of the mesh is constructed by connecting elements 1, 5, and 12, the first row of v shouldsimply contain these values.

If a Gmsh .msh file is to be used, the included utility msh2coords is called to extract the c and v arrays from

7. http://www.geuz.org/gmsh

7

the .msh file, and the mesh geometry can be viewed using the utility meshview .

Using mesh filesTriangular dislocation element meshes are integrated into a Blocks model run by connecting the mesh files to the

.segment file by way of the patchFile and patchTog options. In the .command file (see below), list thepaths to the patch files, and then refer to these files by number in the patchFile parameter of the .segmentfile. The segments whose patchFile parameter is set to a non-zero number (and whose patchTog is set to 1)will be "replaced" by the corresponding mesh file. That is, those segments will contribute nothing to the elasticdeformation portion of the solution (accomplished by setting the segments' locking depth to zero) and instead theelastic contribution will come from spatially variable slip on the triangular dislocation elements comprising the mesh.In general, it is a good idea to make sure that the segments that are replaced by the patch align reasonably well withthe surface trace of the mesh; the code will automatically "snap" the extreme vertices of the mesh to coincide with theextreme endpoints of the segments that it replaces.

Building .sta.data filesGeodetic site velocities are stored in .sta.data files. These have 10 fields per line with each line containing

information on a given geodetic site. An example is given below

240.020 43.590 -0.264 -0.163 0.000 0.000 0.000 7 1 Test_GPS

From left to right the fields are: longitude (degrees), latitude (degrees), east component of velocity (mm/yr), northcomponent of velocity (mm/yr), uncertainty in east component of velocity (mm/yr), uncertainty in north componentof velocity (mm/yr), east-north velocity correlation, a currently unused field, a station "toggle", and an eight characterstation name. If the station toggle is set to 1 the station is included in the model run and it is not included if set to 0.

Building .command files & running BlocksA .command file acts to provide the function Blocks with with information like to the names of the files that

it should use and appropriate weighting for smoothing constraints. In general, it is the file names that are themost important and vary the most but for the sake of completeness we provide a complete listing of a hypotheticalnorthpole.command file:

Segment file name: ./northpole.segmentStation file name: ./northpole.sta.dataBlock file name: ./northpole.blockReuse old elastic kernel: noOld elastic kernel file: ./0000000001/kernels.matSave current elastic kernels: noFault resolution: 500Poissons ratio: 0.25Station data weight: 1Station data weight minimum: 1Station data weight maximum: 1station data weight steps: 1Slip constraint weight: 1e5Slip constraint weight minimum: 1e5Slip constraint weight maximum: 1e5Slip constraint weight steps: 1Block constraint weight: 1e24

8

Block constraint weight minimum: 1e20Block constraint weight maximum: 1e20Block constraint weight steps: 1Locking depth toggle 2: 25Locking depth toggle 3: 15Locking depth toggle 4: 10Locking depth toggle 5: 5locking depth override toggle: nolocking depth override value: 15Triangulated patch files: ./northpole1.msh ./northpole2.mshPatch slip distribution files:Mesh smoothing values: 1 10Surface azimuth of triangular slips:Enforce patch kinematic consistency: 0Set [updip downdip lateral] dip limits to zero slip: 0 0 0 1 1 0Strain calculation method: 1

Note that many of these are deprecated (Fault resolution, Station data weight, Stationdata weight minimum, Station data weight maximum, station data weight steps,Slip constraint weight, Slip constraint weight minimum, Slip constraintweight maximum, Slip constraint weight steps, Block constraint weight, Blockconstraint weight minimum, Block constraint weight maximum, Block constraintweight steps ) but are included for compatibility with the older blocks_sp1 package.

Many of the entries in the .command file are self explanatory, are we here define those that are not:Reuse old elastic kernels: Because calculation of the elastic dislocation partial derivatives for

rectangular and triangular elements is one of the most time consuming steps in a block modeling run, it is possibleto save the partials calculated for one model run and reuse them for subsequent runs. The .segment file is oftenonly slightly modified from one run to the next, so the elastic dislocation partials need be recalculated only for thosesegments that have been added or changed. Setting this entry to yes allows an existing kernel file to be used. Thepath to the kernel file should be specified in the Old elastic kernel file line. Specify yes in the Savecurrent elastic kernels line to generate the kernel file that can be reused in later runs; the file will be savedto the result directory.

Triangulated patch files: Specify the path of the .msh or .mat files describing the mesh geometry,separated by spaces on one line.

Patch slip distribution files: To be used in future versions of Blocks.Mesh smoothing values: Setting the strength of the Laplacian smoothing operator applied in the inversion

takes some trial and error to balance physically unrealistic slip distributions with large data residuals. A large rangeof values, spanning several orders of magnitude, should be evaluated. The smoothing code attempts to normalize thesmoothing operator for element size, such that a single smoothing value should operate similarly regardless of meshdensity. However, best results will be obtained if all of the meshed geometries have roughly the same element size.Smoothing values should be specified for each mesh file, separated by spaces, or a single value applying to all meshesshould be specified.

Surface azimuth of triangular slips: Not fully developed in this version of Blocks. Ideally, thisshould allow the rake of the slip vector on each triangular element to be determined a priori , such that the surfaceprojection of the slip vectors all point in the same direction.

Enforce patch kinematic consistency: If set to 1, the slip vector on all triangular elements will beforced to be consistent with the sign of the nearest rectangular fault segment.

Set [updip downdip lateral] limits to zero slip: Specify 3 numbers for each mesh file,

9

corresponding to boundary conditions on the elements lining the edges of the geometry. Setting these values to 1will enforce zero slip rate (i.e., fully creeping) on the elements lining the updip, downdip, and lateral edges of thegeometry, while setting any value to 0 will enforce no such conditions. The updip and downdip limits will only befound if they mark a contour. That is, if the patch is 15 km deep, all nodes lining the downdip edge must be exactly15 km deep.

Strain calculation method: Can be set to 1, 2, 3, or 4 to specify how internal block strain is calculated.If 1, we assume that the block's geometric centroid serves as the strain tensor reference coordinates, defined as thepoint at which the block strain contribution to the velocity field is zero. Note that, depending on the block geometry,a block's centroid may lie outside of its boundaries. If 2, the reference coordinates are solved for using a 5-parameterlinear estimator. If 3, only the latitude of the reference coordinates are estimated linearly. If 4, a directed forwardsearch algorithm is used to solve for the optimal reference coordinates, which are in turn used as inputs in the linearestimator of all block model parameters including the strain rate tensor components.

Now that all of the neccesary input files have been constructed just set Blocks to running by typing,Blocks(northpole.command) . If you receive "out of memory" errors while the inversion is being carriedout, you can opt to not convert the involved arrays from sparse memory allocation to full memory allocation bycommenting out a single line of the code in Blocks.m . This will generally allow the inversion to complete, butbecause sparse matrices are involved, only one processor thread will be used, and so the inversion will be slower.

OutputEvery model run produces 14 or 15 output files:

1. Obs.sta.data - observed velocities2. Mod.sta.data - model velocities3. Res.sta.data - residual velocities4. Rot.sta.data - rotational component of model velocities5. Strain.sta.data - internal block strain component of model velocities6. Tri.sta.data - elastic component of model velocities from triangular dislocation elements7. Def.sta.data - elastic component of model velocities from rectangular dislocation elements8. label.sta.data - really just for debugging9. Mod.segment - Estimated slip rates and uncertainties on rectangular fault segments

10. label.segment - really just for debugging11. Mod.patch - Estimated slip rates and uncertainties on triangular fault segments12. Mod.block - Estimate block Euler poles and uncertainties13. Stats.txt - Multiple goodness-of-fit statistics, alternative reference frames, residual rankings, and

percentages14. (filename).command - Copy of the .command file used for this model run; good for bookkeeping.15. kernels.mat - Optional file containing the elastic partial derivative matrices, if the Save current

elastic kernels option was set to yes in the .command file.

10