MLOC Command Files
Control over the processing of mloc is managed by commands, of which there are about 70. Most commands are four characters in length (a few are three characters), always given in lowercase. Only a small number of commands are always required for a run. Commands may be entered interactively from the Terminal or read from a text file containing the commands and arguments. In practice we use both approaches, starting with a basic command file that handles commands that are mainly repeated from run to run, and issuing a small number of commands interactively to configure and launch the run. Indeed, a command file cannot be read except via an interactive command (cfil). It is common to edit the command file slightly between runs, but the amount of editing depends on how much control you want to off-load to interactive input. In any case most of the information (notably the event definitions) in a command file stays constant from run to run.
Command files can be given any name, and you could use a simple name (e.g., mloc.cfil) and simply edit it from run to run, keeping the same name. A better practice is to make a new command file for each run (i.e., make a duplicate of the command file from the previous run) and name it after the run ID, e.g., my_cluster1.2.cfil for the second run in the first series of runs for a cluster named my_cluster. Then it is saved with all the output files to provide a clear record of how that run was set up. The filename suffix for a command file .cfil is standard, but it is not required. Command files are stored in the cluster directory with the event data files.
Processing a Command File
When mloc is launched there are several interactive steps that occur after a few program limits are listed:
- Giving a name for the run (used to name all output files)
- Giving the name of the subdirectory of the mloc working directory where the data files for this cluster are stored
$ mloc_a1047 mloc v10.4.7, release date 7/14/2019 Current program limits: nevmax = 200 nqmax = 4000 ntmax1 = 35000 Enter a basename for this run: my_cluster1.2 Enter the name of the data directory: my_cluster1
After this, the program lists all the available commands and asks for interactive command input. Any command can be entered interactively at this point but the normal procedure is to tell mloc to process the command file that has been prepared for this run:
cfil my_cluster1.2.cfil
During processing of the command file (in the main program mloc.f90) the user may be asked for some additional input, or warning messages may be issued. The processing of commands is handled by the subroutines in mloc_commands.f90. When the command file is finished the program asks for more interactive input. The relocation does not begin until the user issues the run command.
Command File Structure
Command files consist of two primary sections. The first section contains commands that control the procedures that will be used for the relocation, affecting all events. The second section, beginning with the first memb command, defines the events to be included in the cluster for this run and allows the user to issue commands which are event-specific. Some commands can be issued in either section but have a different action, depending on whether they are issued before any events have been defined.
Order of commands
Within the first section there is considerable (maybe total, but it has not been tested) flexibility in the order in which commands are given. In each event definition block, the memb command must come first but otherwise the order of commands is arbitrary. Within the event definition section as a whole it is strongly advised to keep events in chronological order, but it is not required.
Killing events
The easiest way to remove an event from a cluster is to delete the lines of its event definition block from the command file, but there may be reasons to want to keep a record of its existence in the command file even though it is not being relocated. It is also quite common to temporarily “kill” events in order to work with a smaller or better-constrained set of events.
mloc has two methods to meet these needs. To eliminate a contiguous block of events the kill command (with arguments on and off) is used. To kill a single event, the preferred method is to use kill as an argument after the memb command.
Comments
Any text after an exclamation point “!” in a command line is taken as a comment. There is also a “comment” command comm which is useful for comments that are not command-specific and for temporarily preventing a command from running.
Repeated commands
Most commands can be repeated; the last instance is the one that will control the relocation. This feature is used often for the dep_ family of commands that specify the starting focal depth. The fourth character is taken as a flag to indicate the source of the depth constraint. It is very common to have several estimates available for the depth of an event and it is useful to be able to keep them all at hand in the command file.
Defaults
It is possible (but mostly pointless) to make a run of mloc with no commands except the ones that define events, because all parameters that control how the relocation is done have defaults. The defaults are defined in the main program mloc.f90. In this case the relocation would be done using teleseismic P arrivals and the ak135 travel time model. Data would be weighted inversely to their uncertainty (using the phase-specific default reading errors) and phase re-identification would be done. All four hypocentral parameters would be free. Only a base plot would be made, as well as the core output text files.
Defining Events
Events are defined with a minimum of three commands, for example:
memb even 20090807.1859.26 inpu 20090807.1859.26.mnf
The memb command starts the definition of a new event. The even command provides an identifying name for the event that will appear throughout the output files. It is normally derived from the filename of the event data file itself, which is supplied in the inpu command. Event data files are normally named with an origin time, which does not have to exactly match that of any hypocenter (there can be several) in the event file itself but should be pretty close. Additional commands could be given and they would apply only to the current event until another memb command is encountered.
Except for the very smallest clusters, assembly of the event definition section would be very tedious to do by hand, so it is normally done by one of several utilities, especially ones that search through a concatenated set of event files (i.e., a bulletin) and extract individual events for a cluster.
Terminating a Command File
No special steps are required to terminate a command file. It normally ends with the definition of the last event.
An Example
This is the command file from the ridgecrest3.1 run of mloc for the Ridgecrest, California cluster that was used to illustrate the various summary plots, with comments added for many of the commands to explain their function. Most of the event definition section has been removed.
pltt 1 2 3 4 5 6 7 8 ! All standard plots except S-P (tt9) comm ccat ridgecrest_summary.txt ! This command is commented out comm plot 1: July 4, 2019 sequence ! Comment describing the selected event plot fdhp on ! Make the plot of a histogram of focal depths rdpp all ! Make relative depth phase plots for any event that has the appropriate readings eplt on ! Make an ellipse plot splt on ! Male a seismicity plot epap Pn 15. 0 ! Make an Empirical Path Anomaly plot for Pn out to 15°, no lines connecting source and station tt5e 20190704.1733.49 ! Make a local travel time plot (tt5) for the event 20190704.1733.49 tt5s LRL ! Make a station-specific travel-time plot (tt5) for station LRL dem1 globe ! Use the GLOBE DEM for topography sstn ridgecrest3/ridgecrest_stn.dat ! Supplemental station file for this cluster lmod ridgecrest3/ridgecrest.cr ! Local crustal model bdps tables/stn/bdps.dat ! List of stations that report bogus depth phases ttou Lg ! Make an output file of Lg travel times and distances lgtt 0.03 31.68 1.6 ! Custom Lg travel time model, y-intercept and slope (s/deg), used beyond 1.6° ppri pP ! Do not re-identify pP phases ppri sP ! Do not re-identify sP phases rhdf ridgecrest2.42.hdf_dcal ! Take starting locations from a previous run rfil ridgecrest2.42.rderr ! Take empirical reading errors from a previous run tfil ridgecrest2.42.ttsprd ! Take data on the spread of residuals for different phases from a previous run dcal on ! Use direct calibration phyp off ! Use both P and S phases to locate the hypocentroid hlim 0. 0.8 ! Use arrival time data out to 0.8° for the hypocentroid clim 0. 180. ! Use arrival time data at all epicentral distances to estimate cluster vectors (relative locations) wind 3 4 ! Windowing limit and taper, in terms of the spread of each phase, to disregard gross outliers frec 1 1 0 1 ! Free parameters for cluster vectors (lat, lon, OT) freh 1 1 0 1 ! Free parameters for hypocentroid (lat, lon, OT) depc 15 ! Cluster default depth, will be over-ridden by rhdf command memb ! Declare a new event even 19930520.2014.14 ! Event name inpu 19930520.2014.14.mnf ! Input file depm 15.3 1.0 ! focal depth and uncertainty from a free-depth relocation, supercedes rhdf and depc commands depn 13 3 ! focal depth and uncertainty from near-source data, supercedes all previous depth estimates memb even 19950920.2327.35 inpu 19950920.2327.35.mnf depm 21.6 0.9 ! ridgecrest2.29 depl 17 4 ! focal depth and uncertainty from local-distance data, supercedes all previous depth estimates ... (more event definition blocks) ... memb even 20190711.2345.18 inpu 20190711.2345.18.mnf depm 12.1 0.6 ! ridgecrest2.32 depn 12 3 plot 1 ! Plot this event in the first selected event plot (there can be multiple such plots) memb even 20190712.1311.37 inpu 20190712.1311.37.mnf depm 19.0 0.5 ! ridgecrest2.32 depn 19 3 plot 1