Options and file formats for stand-alone programs

August 26, 2026 · View on GitHub

Each program is invoked with the same following options:

-p  Specify parameter file (mandatory)
-h  print short help message
-k  Save model in VTK format
-v  Verbose mode
-t  Measure time to build grid and perform raytracing
-s  Dump secondary node coordinates to ascii file ((D)SPM method only)

Parameter file

The parameter file is used to specify the raytracing parameters. It is a plain ascii file and each line has the following format:

value          # keyword,

The keywords are :

basename : each output file will start with this basename
modelfile : name of file holding grid definition, currently VTK and gmsh formats are accepted (see below)
velfile : velocity in physical domains defined in gmsh files
slofile : slowness of the cells defined in gmsh files
srcfile : name of file containing source location and t0
rcvfile : name of file containing receiver location
secondary nodes : number of secondary nodes for the shortest-path method (SPM)
number of threads : perform raytracing for multiple sources simultaneously using this number of threads
inverse distance : use inverse distance instead of linear interpolation for computing slowness at secondary nodes (SPM in 3D)
metric order : metric used to built sweeping ordering (FSM, see Qian et al. 2007) default is 2
epsilon : convergence criterion for the fast sweeping method (FSM, see Qian et al. 2007). The sweeps stop once the mean per-node change in traveltime between two successive iterations falls below this value (i.e. the L1 sum of |Δt| divided by the number of nodes), so the same value behaves consistently regardless of grid size. Default is 1.e-5. Iterating much below the medium's discretization error buys no accuracy; values around 1.e-5 typically reach the floor while avoiding tens of redundant WENO3 iterations. Note: because the WENO3 update is non-monotone early on, do not set epsilon larger than the per-node change of the first iteration, or the loop may stop prematurely.
max number of iteration : max number of sweeping iterations (FSM) default is 20
saveGridTT : save traveltime over whole grid, in ASCII file if 1, in VTK format if 2, or in binary format if 3.
single precision : work with float rather than double
fast marching : use fast marching method if value == 1 (implemented on 2D & 3D unstructured meshes only)
fast sweeping : use fast sweeping method if value == 1 or 2 (2 will attempt to run the OpenCL implementation)
dynamic shortest path : use dynamic shortest path method if value == 1
tertiary nodes : number of tertiary nodes to use with DSPM
src radius tertiary: radius around source for including tertiary nodes
process reflectors : use reflectors as sources to compute reflected arrival times (experimental)
saveRayPaths : Save raypaths in VTK format
raypath high order : compute traveltime gradient on unstructured meshes with high order least-squares (default is 1)
fsm high order : use 3rd order weighted essentially non-oscillatory (WENO) operator with fast sweeping in rectilinear grid if value == 1 (default is 0)
traveltime from raypath : use backward raytracing step to compute traveltimes (currently implemented on 3D unstructured meshes only)
save M : compute and save the matrix M of partial derivatives of traveltime with respect to model slowness along the raypaths (the sensitivity / ray matrix used in tomography). Enable with 1. Default is 0. Implies raypath computation.
project Tx Rx : project the source and receiver coordinates onto the mesh before raytracing, useful when Tx/Rx points lie slightly off the mesh. Enable with 1. Default is 0. (unstructured meshes)
interpolate velocity : when computing slowness at secondary/tertiary nodes, interpolate velocity (then convert to slowness) rather than interpolating slowness directly; can improve accuracy where strong slowness gradients are present. Enable with 1. Default is 0.
rotated template : for the fast sweeping method on rectilinear grids, also use the rotated (diagonal) finite-difference stencils in addition to the standard axis-aligned template (see Qian et al. 2007), improving accuracy for wavefronts travelling obliquely to the grid. Enable with 1. Default is 0.
source radius : radius around each source within which node traveltimes are initialized analytically (assuming a locally homogeneous medium) instead of by the solver; improves near-source accuracy. A value of 0 disables it. Default is 0.
raypath minimum distance : minimum distance tolerance used during raypath reconstruction (e.g. to decide when a node or the source has been reached). Default is 1.e-5.
translate grid origin : internally translate the grid so its origin is at (0,0,0) before raytracing, improving numerical conditioning for meshes defined far from the origin. Enable with 1. Default is 0. (unstructured meshes)
min nb Tx per thread : when the number of threads is chosen automatically (i.e. number of threads is 0), assign at least this many sources (Tx) to each thread, which caps the thread count when there are few sources. Default is 5.
profile : when using the OpenCL fast sweeping implementation, print a GPU profiling breakdown (sweep wall-clock time, kernel execution time and its fraction of the wall time, host/device transfer times, and number of kernel launches) at the end of the run. Independent of verbose mode. Enable with 1. Default is 0.

The following keywords are accepted aliases for keywords listed above:

number of dynamic nodes : alias for tertiary nodes.
gradient method : alias for raypath high order.
radius dynamic nodes : alias for src radius tertiary.

An example is shown below (note that keywords must be comprised between a hashtag and a comma):

ttcr2ds        # basename,
model2ds.msh   # modelfile,
model2ds.vel   # velfile,
src.dat        # srcfile,
rcv.dat        # rcvfile,
1              # number of threads,
1              # saveGridTT,
5              # secondary nodes,
1              # saveRayPaths,

Model file

Rectilinear grids

Models can be defined in VTK (http://vtk.org) format or custom GRD format.

VTK files: These files must hold the slowness data, which can be defined either in terms of slowness or velocity, as cell data for grid with cells of constant slowness or as point data for slowness defined at grid nodes. Extra cell arrays may be added to describe an anisotropic medium, see Anisotropic models below.

GRD files: For this format, the grid dimensions are given in a file with a .grd extension. The format is the following, where values are given for x, y and z in that order (2D grids should have 0 cells in y):

Example example.grd

100 0 200 # number of cells,
1 1 1 # size of cells,
0 0 0 # origin of grid,

Slowness values should be provided separately in a slofile. Slowness values can be assigned to nodes or cells, depending on the total number of slowness values given in the file: if the number is equal to the number of nodes, then the values are assigned to nodes and if the number is equal to the number of cells then the values are assigned to the cells.

** Important **

In 2D, the values are ordered for z incremented first, then x, while in 3D the order is x first, then y and finally z, i.e.

In 2D, ordering should correspond to coordinates

xmin      zmin
xmin      zmin+dz
xmin      zmin+2dz
  :        :
xmin      zmax
xmin+dx   zmin
xmin+dx   zmin+dz
  :        :
xmax      zmax

In 3D, ordering should correspond to coordinates

xmin      ymin     zmin
xmin+dx   ymin     zmin
xmin+2dx  ymin     zmin
  :        :        :
xmax      ymin     zmin
xmin      ymin+dy  zmin
xmin+dx   ymin+dy  zmin
xmin+2dx  ymin+dy  zmin
  :        :        :
xmax      ymin+dy  zmin
  :        :        :
xmax      ymax     zmin
xmin      ymin     zmin+dz
xmin+dx   ymin     zmin+dz
  :        :        :
xmax      ymin     zmin+dz
xmin      ymin+dy  zmin+dz
  :        :        :

etc

Note regarding the fast sweeping method on rectilinear grids

The 3D implementations require that the cells must be cubic. Only the first value for the size of cell is used when building the grids.

OpenCL accelerated implementations of the sweeping method are provided for 3D rectilinear grids. Depending on hardware, the OpenCL implementation might not run if double precision is requested, in which case the code falls back to the CPU version. In the current version, multi-threading is disabled when using OpenCL implementations to avoid saturating the GPU.

Unstructured meshes

Models are defined in either VTK (http://www.vtk.org) or gmsh (http://geuz.org/gmsh/) files.

VTK files: As for rectilinear grids, these files must hold the slowness data, which can be defined either in terms of slowness or velocity (see routines in files grids.h and VTUReader.h for details). Extra cell arrays may be added to describe an anisotropic medium, see Anisotropic models below.

MSH files: gmsh file format version 2.2 is supported. This format does not allow storing cell attributes, so slowness data must be stored in other files. There are two options: the first is to have a file holding the slowness values for each cell, in the same cell order than found in the msh file. This type of file corresponds to the slofile found in the parameter file. The other option is to define velocity values for physical entities (volumes in 3D or surfaces in 2D) found in msh files. These data are given in velfile. The following gives an example of a geometry file used by gmsh to generate the mesh, and the associated velfile.

Example model2ds.geo

lc = 25;

Point(1) = {    0,    0, 200, lc };
Point(2) = {    0, 1000, 250, lc };
Point(3) = { 1000, 1000, 225, lc };
Point(4) = { 1000,    0, 275, lc };
Point(5) = {    0,  300, 175, lc };
Point(6) = {    0,  600, 300, lc };
Point(7) = {  500, 1000, 150, lc };
Point(8) = { 1000,  700, 200, lc };
Point(9) = { 1000,  250, 200, lc };
Point(10) = { 500,    0, 350, lc };
Point(11) = { 500,  750, 150, lc };
Point(12) = { 600,  300, 375, lc };

Spline(1) = { 1, 5, 6 };
Spline(2) = { 2, 7, 3 };
Spline(3) = { 3, 8, 9 };
Spline(4) = { 4, 10, 1 };

Spline(5) = { 6, 11, 3 };
Line(6) = { 6, 2 };
Spline(7) = { 9, 12, 1 };
Line(8) = { 9, 4 };

Line Loop(1) = { 1, 5, 3, 7 };
Line Loop(2) = { 2, -5, 6 };
Line Loop(3) = { 8, 4, -7 };

Ruled Surface(1) = { 1 };
Ruled Surface(2) = { 2 };
Ruled Surface(3) = { 3 };

Physical Surface("S1") = {1};
Physical Surface("S2") = {2};
Physical Surface("S3") = {3};

Note that it is possible to impose the creation of given point nodes related to geometrical entities (handy for isolated source points), by defining such points as "physical points" in the geometry file.

Example model2ds.vel

"S1"    3000
"S2"    5000
"S3"    2000

Slowness defined at grid nodes for unstructured meshes

It is possible to define slowness at grid nodes rather than for mesh cells. This improves accuracy for models where slowness gradients are present. For VTK files, this is done by assigning slowness or velocity values at nodes. For MSH files, this is done by using a slofile with slowness values for each mesh node in the order found in the msh file (velfile cannot be used in this case).

Anisotropic models

An anisotropic medium is described by adding cell arrays to the VTK file, alongside (or instead of) the slowness. The model is chosen from the arrays the file carries: no keyword in the parameter file selects it.

Anisotropy is a property of a cell, so it requires a model of constant-slowness cells — arrays given as point data are ignored — and it is used by the shortest-path method only. A file carrying anisotropy arrays raytraced with the fast sweeping, fast marching or dynamic shortest-path method is read as isotropic.

arrays in the file	model	2D `.vtr`	2D `.vtu`	3D `.vtr`	3D `.vtu`
`xi`	elliptical	yes	yes	—	—
`xi`, `theta`	tilted elliptical	yes	yes	—	—
`s2`, `s4`	weakly anelliptical	yes	yes	—	yes
`chi`, `psi`	ellipsoidal	—	—	yes	yes
`Vs0`, `gamma`	transversely isotropic, SH wave	—	—	—	yes
`Vp0`, `Vs0`, `epsilon`, `delta`	transversely isotropic, qP and qSV waves	—	—	—	yes

These are the same models the Python classes take through their aniso argument; the anisotropy page of the documentation describes each of them, and gives the traveltime and the sensitivities they produce.

What Slowness means. For most models the Slowness (or Velocity) array is still required, but it is not always the same slowness:

elliptical and tilted elliptical (2D): the horizontal slowness sx, with xi = sz/sx and theta the tilt angle of the symmetry axis, in radians;
weakly anelliptical: the vertical slowness, with s2 and s4 the second- and fourth-order coefficients;
ellipsoidal (3D): the vertical slowness sz, with chi = sx/sz and psi = sy/sz. The axes of the ellipsoid are aligned with the axes of the model;
transversely isotropic (Vs0/gamma, or Vp0/Vs0/epsilon/delta): no Slowness array is needed, and any present is ignored. These media are described by their axial velocities and Thomsen's parameters, so the file may carry no slowness at all.

Incomplete sets are refused. Giving epsilon without delta, s2 without s4, chi without psi, or epsilon/gamma without the velocity they need, stops the program with a message rather than falling back to an isotropic run.

When several models could be read the first match wins, in the order the table lists them: theta before xi before s2/s4 in 2D, and epsilon before gamma before s2/s4 before chi/psi in 3D.

The qP wave is the one modelled for a Vp0/Vs0/epsilon/delta medium. The stand-alone programs offer no way to ask for qSV; use the Python classes and their set_phase method for that.

Example: a 3D tetrahedral mesh in model.vtu holding the cell arrays Vp0, Vs0, epsilon and delta is raytraced with

ttcr3d_vti     # basename,
model.vtu      # modelfile,
src.dat        # srcfile,
rcv.dat        # rcvfile,
5              # secondary nodes,
1              # saveRayPaths,

no keyword being needed beyond those a normal run takes.

Src and Rcv files

These are simple ascii file holding the coordinates of the source points and initial time (t0) at the points, and the coordinates of the receivers. Note that files used by ttcr2d should not have y coordinates. The following are two examples for ttcr3d.

Example src1.dat

2
0 0 0 0
1 0 0 0

Example rcv.dat

Note that one "source" can have many points in space. When raytracing is needed for many sources, simply add the files in the parameter file, as shown below. In that case, setting number of threads to 3 will tell the program to perform raytracing simultaneously for the three sources. Note that number of threads should not be set to a number larger than the number of CPU cores of your machine. If you have more sources that CPU cores, set number of threads to the number of cores, and raytracing will automatically be performed in "batches".

ttcr2ds        # basename,
model2ds.msh   # modelfile,
model2ds.vel   # velfile,
src1.dat       # srcfile,
src2.dat       # srcfile,
src3.dat       # srcfile,
rcv.dat        # rcvfile,
3              # number of threads,
1              # saveGridTT,
5              # secondary nodes,
1              # saveRayPaths,