Menu Close


focimt is the stand-alone command line application for performing the seismic moment tensor inversion in time domain optimized for local-to-regional applications and seismic networks (Cartesian coordinate system is used). The core of the program is based on the formal description presented in Fitch et al. (1980) and Wiejacz (1992). The application uses first P-wave motion amplitudes and duration of the first P-wave ground velocity pulse to invert for the unconstrained full moment tensor. In addition, the constrained trace-null and double-couple moment tensors may be calculated as well. The calculated full moment tensor can be decomposed into isotropic (ISO) and deviatoric parts (CLVD/DC). The output information can be exported to highly customized output text files. focimt also provides high-quality graphical representation of the moment tensor inversion in a form of beach balls, exported to raster and vector file formats (PNG, PDF, PS and SVG). The precompiled binary is available for Windows; the source code for Linux and macOS is included.

The current version of focimt is 4.4.1, distributed with hybridMT 2.0.0 (October 6th, 2026).

Main features

  • Full (unconstrained), deviatoric (trace-null) and double-couple constrained moment tensors in one run (option -s FTD), L1 or L2 norm (-n).
  • Decomposition into ISO, CLVD and DC components following Jost and Herrmann (1989) or Vavryčuk (2001).
  • Two input formats: amplitudes with takeoff angles and distances (RAW format), or station and event coordinates with a 1D velocity model and the built-in ray tracer (-m).
  • Uncertainty assessment: station Jacknife test (-j) and resampling of the input data, i.e. reversed polarities, rejected stations, perturbed amplitudes and takeoff angles (-rp, -rr, -ra, -rt).
  • Many events in one input file, e.g. whole catalogs.
  • Beach balls in PNG, SVG, PDF and PS format with stations, P/T axes, nodal planes and customizable colours, equal-area or equal-angle projection, lower or upper hemisphere; drawing of fault plane solutions and stations without an inversion (-f, -fj, -fs).
  • Customizable ASCII output (-d): fault planes, P/T/B axes, decomposition, moment tensor components, seismic moment and magnitude, errors.

What is new in version 4.4.1 (compared with 4.0.3)

  • Corrected shading of the T and P axes of the beach balls (nearly pure double-couple solutions and nodal lines passing through the centre of the plot were shaded incorrectly).
  • Corrected colour options: all colour options were shifted by one and the option -cl stopped the program; both are fixed.
  • The input data export (-ei) writes the amplitudes already corrected for the angle of incidence; up to 256 channels per event.

Use from MATLAB and Python

focimt is a part of the hybridMT moment tensor inversion and refinement software package. The package contains the MATLAB wrapper function focimt.m and, from version 2.0.0, the Python package hybridmt, which allow to conveniently handle the input parameters and the inversion results directly in MATLAB or Python. Numerous parameters can be specified to manage the input data, define the seismic moment tensor inversion/optimization parameters as well as to handle the properties of graphical and text output. Both also provide the Hybrid Moment Tensor refinement of event clusters. The package contains extensive HTML/PDF documentation with examples and tutorials. For details see the dedicated hybridMT webpage.

Authors

Grzegorz Kwiatek and Patricia Martínez-Garzón.

Referencing

When you find focimt application useful, please refer to it in your work:

Kwiatek, G., Martínez-Garzón, P. and M. Bohnhoff (2016). HybridMT: A MATLAB/Shell Environment Package for Seismic Moment Tensor Inversion and Refinement. Seismological Research Letters 87 (4), DOI: 10.1785/0220150251.

Download

focimt is part of the hybridMT software package, which contains the Windows binary and the source code of focimt, its extensive documentation, the MATLAB wrapper focimt.m and the Python package hybridmt. Please download the hybridMT package from the dedicated site to get the newest version of the focimt tool. To compile focimt under Linux or macOS, follow the instructions in src/howto_compile_focimt.txt of the package (the Cairo graphics library is required).

Documentation

To get the list of all command line options of focimt command line tool, execute:

focimt -h

and to display the version:

focimt -v

The detailed documentation of focimt command line options as well as examples of application are presented in [wpfilebase tag=fileurl id=35 linktext=’hybridMT software package manual’ /]. Below you will find a couple of examples of application of the command line tool.

License

focimt is licensed under GNU General Public License (GPL).

Quick example

Using focimt from the command line (or equivalently the focimt.m MATLAB routine or the Python function focimt, both bundled in the hybridMT package) is very easy. Having the ASCII input file containing event and phase data, the moment tensor inversion may be started directly from the console window (or from the MATLAB command prompt by starting the line with an exclamation mark):

focimt -i example1.txt -s FTD -t PNG -p SU -z 300 -d M

The moment tensor inversion results in generation of output ASCII files containing the moment tensor inversion results and a graphical representation of the solution in a form of a beach ball plot. The equivalent call from the MATLAB command prompt using the focimt.m routine looks as follows:

Solution = focimt('example1.txt','BeachBallFormat','PNG','Projection','schmidt','Hemisphere','upper','BeachBallSize',300);

resulting in output parameters being stored in the output cell array Solution that can be easily further used in MATLAB environment. The same in Python:

from hybridmt import focimt
result = focimt('example1.txt', beach_ball_format='PNG', projection='schmidt', hemisphere='upper', beach_ball_size=300)
result.solution[0].full.ISO      # percentage of the isotropic component

All calls generate graphical representation(s) of the moment tensor solution as in the following picture:

More examples

Station Jacknife test of the double-couple solution (each additional nodal line is a solution without one of the stations):

focimt -i example1.txt -s D -j -t PNG

Resampling of the input data: 100 additional inversions in which about 1% of the polarities are reversed:

focimt -i example1.txt -s D -rp 100/0.01 -t PNG

Full moment tensor with the L1 norm, with the fault planes, axes, decomposition and moment tensor in the ASCII output file:

focimt -i example1.txt -s F -n L1 -d DWAFT -o result

Input in the 1D velocity model format (station and event coordinates), with the velocity model in the file vmodel.txt:

focimt -i example2_1d.txt -m vmodel.txt -s F -t PNG

Drawing fault plane solutions (one main and two additional nodal planes) together with two stations, without an inversion:

focimt -o fault -fj 11/60/-50:15/65/-42:17/55/-55 -fs 10/80/1/A:130/10/-1/B -z 300 -t PNG

Beach balls in PNG and SVG format with custom colours of the T and P axes shading (red/green/blue and opacity):

focimt -i example1.txt -s D -t PNG,SVG -ct 1/0.5/0/1 -cp 0.8/0.8/0.8/1

Beach balls drawn by focimt: full moment tensor, Jacknife test, polarity resampling and drawing of nodal planes with stations:

Beach balls drawn by focimt: full moment tensor, Jacknife test, polarity resampling and drawing of nodal planes with stations
Beach balls drawn by focimt: full moment tensor, Jacknife test, polarity resampling and drawing of nodal planes with stations

More examples on how to use the focimt command line tool are presented in the program documentation, which is a part of the hybridMT package.

FAQ

  • What is the magnitude limit for application of fociMT or hybridMT algorithms?

    • The fociMT algorithm is point-source moment tensor inversion and the fault rupture processes (e.g. directivity or spatial changes in elementary moment tensors) are NOT considered. As such, the algorithm is valid for events with simple source time functions that can be represented by a single pulse. Therefore, it is suggested to use the algorithm for events with moment magnitudes not exceeding Mw 4.

  • Is fociMT algorithm based on full waveform inversion?

    • No. The input for moment tensor inversion using fociMT algorithm is area below first P-wave ground displacement pulse with sign information. As such, the inversion algorithm fall into the class of “amplitude MT inversion” algorithms (i.e. it is different from e.g. ISOLA algorithm)

  • What is the “omega” parameter in the focimt input file and how to calculate it?

    • focimt_seismogram“omega” parameter which is a part of ASCII input file is basically the area below the first P-wave ground displacement pulse (in time domain) or equivalently the spectral level taken from the amplitude spectrum of ground displacement pulse. The unit of “omega” parameter is [m * s] (meter times second), and it comes from the fact that we multiply the amplitude of first P-wave pulse using ground displacement seismogram in [m] by the half of duration of the first P-wave pulse in [s]. Regardless of whether time or frequency domain was used to extract the “omega” value, the parameter should contain the sign information. The sign of “omega” is in accordance with the seismological convention, i.e. it is positive for the positive first P-wave ground displacement amplitude (i.e. ground motion AWAY from the seismic source) and negative otherwise (ground motion TOWARDS the seismic source).

      In case of simple impulsive source time functions it is typically not necessary to calculate the integral of ground displacement first P-wave pulse. Instead, the amplitude D (cf. picture) including sign information of first P-wave pulse may be taken from ground displacement seismogram (the seismogram should be calibrated to [m]) and multiplied by the the rise time (i.e. time interval between the P-wave onset and P-wave amplitude, t_max-t_ons in seconds [s]). In this case, the integral of the pulse is simply replaced by the area of the triangle.

  • What full moment tensor decomposition scheme is used in focimt.m?

    • The MATLAB wrapper focimt.m has no option for changing the decomposition scheme, which is currently fixed to Jost and Herrmann’s (1989) approach. However, the focimt application has implemented an alternative decomposition scheme based on Vavrycuk’s (2001) approach. In focimt application this is specified by option -d D or -d Y (see the documentation of focimt application for details). Therefore, the hardcoded decomposition scheme in focimt.m may be changed from Jost and Herrmann’s to Vavrycuk’s approach simply by changing the following line from (note change from “D” to “Y” in option -d):

      commandline = ['-i ' temp '.txt -d DWAFTUMVE -o ' temp ' -s ' solutions ' -n ' normfunc ' ' bbsize ' ' bbformat ' ' bbproj ' ' jacknife ' ' bootstrap ' ' vmodel ' ' ball];

      to

      commandline = ['-i ' temp '.txt -d YWAFTUMVE -o ' temp ' -s ' solutions ' -n ' normfunc ' ' bbsize ' ' bbformat ' ' bbproj ' ' jacknife ' ' bootstrap ' ' vmodel ' ' ball];

      Future version of focimt.m implement the decomposition switch parameter.

  • How should I provide takeoff angle in RAW ASCII file format?

    • focimt_coordinatesThe takeoff angle is measured in degrees from dowgoing ray (towards the center of Earth) direction. The seismic ray leaving the source purely up (towards the Earth surface) has takeoff angle of 180 degrees. The ray leaving earthquake source towards center of Earth has a takeoff angle of 0 degrees.

  • What is the azimuth convention for RAW ASCII file format?

    • The azimuth of a vector from the seismic hypocenter to the seismic station is measured in degrees, and it is positive from north towards east. 0,90,180, and 270 degrees corresponds to the station located North, East, South, and West from the earthquake hypocenter.

  • What is the incidence angle convention for RAW ASCII input file?

    • focimt_coordinatesThe angle of incidence in RAW ASCII input file follows the standard seismological convention. The angle of incidence to the sensor is measured in degrees from down direction (towards center of Earth). In other words, the seismic ray pointing directly up (perpendicular towards the surface) has 0 degrees incidence angle and pure horizontal ray (parallel to the surface) has 90 degrees incidence angle.

      Note #1: In case of pure horizontal ray (incidence = 90) one should not expect P-wave arrival to be visible on vertical component. Phases with incidence angle = 90 degrees should be disregarded from processing.

      Note #2: Large values of incidence angle (>80 degrees) leads to high corrections for “omega” parameter, as the “omega” is divided by the cosine of the angle of incidence. This typically leads to overestimation of total and scalar seismic moment, as well as it may influence the moment tensor decomposition.

  • Why I get error message on “incorrect expression or statement” when running drawhudsonnet.m or drawstereonet.m?

    • If you get error similar to this:

      >> drawhudsonnet;
??? Error: File: drawhudsonnet.m Line: 119 Column: 3
Expression or statement is incorrect--possibly unbalanced (, {, or [.

      it is likely due to the fact that your version of MATLAB does not support empty output arguments that are specified in MATLAB as “~” (tilde character). If possible, please update your MATLAB to the newest version that handles empty output arguments. Alternatively, please change every null output variable “~” to any valid and not used variable name, e.g. “dummy”: 

      [~,DD] = eig(M);

      to

      [dummy,DD] = eig(M);

      This problem will be resolved in future version of hybridMT.

  • Why I receive error messages “Argument ‘###’ failed validation with error: ####”

    • Consider a scenario of executing the drawstereonet.m function:

      [X,Y] = drawstereonet([10 20 30 40],[50 60 70 80]);
??? Error using ==> drawstereonet at 43
Argument 'AZM' failed validation with error:
Undefined function or method 'ismatrix' for input arguments of type 'double'.

      This error results from the fact your MATLAB version does not contain ismatrix() routine. If it is possible, please update the MATLAB to the newest version. Alternatively, you can try to disable the validation routine. In case of example above, by changing line:

      p.addOptional('AZM', [], @(x) ismatrix(x) && isnumeric(x) );

      to:

      p.addOptional('AZM', [], @(x) isnumeric(x) );

       

Acknowledgements

focimt uses portions code by Pawel Wiejacz (Institute of Geophysics, Polish Academy of Sciences, Warsaw, Poland) . focimt binaries uses CAIRO library (http://cairographics.org/). The source code also contains routines from PSMECA program, which is a part of Generic Mapping Tools (GMT) software package available to download from http://gmt.soest.hawaii.edu/. The 1D velocity model ray-tracing routines were translated from hypoDD v1.3 package by Felix Waldhauser, see http://www.ldeo.columbia.edu/~felixw/hypoDD.html for details.

The Authors wish to thank Pawel Wiejacz, Boguslaw Domański, Marek Burdzy, Grzegorz Makowski, Marian Król, Wojciech Dębski, Ilona Kwiatkowska, Marcin Pussak, Anita Zych-Kotwicka, Artur Kotwicki, Łukasz Rudziński, Grażyna Maziarz-Wiorek, Nikos Melis, Beata Orlecka-Sikora, Bożena Hersztowska, Katrin Plenkers, Oliver Germer, Grzegorz Lizurek, Wojciech Białoń, Maria Kozłowska, Konstantinos Leptokaropoulos, Joanna Kocot, Jerzy Giza, Krystyna Stec for help, feedback and beta-testing of the software.

References

Fitch, T. J., D. W. McCowan, and M. W. Shields (1980). Estimation of seismic moment tensor from teleseismic body wave data with application to intraplate and mantle earthquakes, J. Geophys. Res. 85, 3817–3828.

Jost, M. L., and R. B. Herrmann (1989). A student’s guide to and review of moment tensors, Seismol. Res. Lett. 60, 37–57.

Knopoff, L., and M. J. Randall (1970). The compensated linear-vector dipole. A possible mechanism for deep earthquakes, J. Geophys. Res. 75, 1957–1963.

Vavryčuk, V. (2001). Inversion for parameters of tensile earthquakes, J. Geophys. Res. 106, B8, 16339–16355.

Wiejacz, P. (1992). Badanie mechanizmów wstrząsów górniczych przy wykorzystaniu tensora momentu sejsmicznego, Institute of Geophysics, Polish Academy of Sciences.