Programmatic Access

TauP can be used as a library in addition to the command line tools. The web interface provides an alternative for non-JVM languages.

Java

As it is written in Java, TauP is most easily used by other Java programs. A very simple Java program to calculate arrival times is below. The general flow is that you start with a VelocityModel and convert to a TauModel, unless using one of the built in TauModels. Then create SeismicPhase objects for each phase of interest from the model. Lastly, use the phase to calculate Arrival objects for a distance.

Javadocs for the package are at available at javadoc.io.

While the TauP jar and its dependencies are included in the distribution, it is often easier to depend on the publication within the Maven Central repository as this facilitates download and updates and provides for automatic dependency resolution when using a build tool like maven or gradle.

Converting the initial model for a source depth is more costly than calculating arrivals at a distance, so it is usually more efficient to process all stations for each earthquake rather than all earthquakes for a station.

package edu.sc.seis.example;

import edu.sc.seis.TauP.*;

import java.io.IOException;
import java.util.List;

public class TimeExample {

    public void calcTimes() throws TauPException, IOException {
        // A standard model can be loaded by name
        TauModel ak135Model = TauModelLoader.load("ak135");
        // or a custom velocity model, from a file in current directory, can be
        // loaded and then turned into a TauModel
        VelocityModel vMod = TauModelLoader.loadVelocityModel("mymodel.nd");
        TauModel tMod = TauModelLoader.createTauModel(vMod);

        // A seismic phase for a phase name like 'P' can be created for that model
        double sourceDepth = 100;  // earthquake depth in kilometers
        double receiverDepth = 0;  // seismometer depth in kilometers if not at the surface
        SeismicPhase P_phase = SeismicPhaseFactory.createPhase("P", tMod, sourceDepth);

        //
        List<Arrival> arrivalList = DistanceRay.ofDegrees(45).calculate(P_phase);
        for (Arrival a : arrivalList) {
            System.out.println(a.getName()+" "+a.getDistDeg()+" "+a.getTime());
        }
    }

    public static void main(String[] args) throws Exception {
        TimeExample ex = new TimeExample();
        ex.calcTimes();
    }
}

HTTP Access

While using Java, or perhaps another language that can run on the JVM, is the most computationally efficient way to access TauP, it does limit the languages available. For other languages, the simplest way is to make use of the built in web access within TauP to access the tools via an HTTP request returning JSON.

Running taup_web in the distribution will start up a web server on port 7049 to allow this type of access, although only from connections on the local machine.

An example in Python using the Requests library is below. Each of the normal command line tools are available via this web interface, and almost all command line arguments can be sent via a corresponding URL query parameter by removing leading dashes. For example to calculate the at a distance in kilometers, where the command line tool uses ‘–km 100’, the URL would include ‘km=100’ like:

http://localhost:7049/time?phase=P,S&km=100&format=json

Boolean command line flags, like ‘–amp’, can be given a true value as in ‘amp=true’. Many options have default values, just as in the command line tools. It may be helpful to experiment with the web gui at

http://localhost:7049/taup.html

to see how the URL is encoded and what the results are. Note that the web form does not yet include all possible parameters that the web tools support.

import requests

params = {
    'model':'ak135',
    'evdepth':100,
    'phase':'P,S',
    'degree':35,
    'amp': True,
    'format':'json'
}

r = requests.get('http://localhost:7049/time', params=params)

jsonTimes = r.json()
for a in jsonTimes["arrivals"]:
    print(f"{a['phase']} {a['distdeg']} {a['time']}")