Cake manual

Cake is a tool which can be used to solve classical seismic ray theory problems for layered earth models (layer cake models).

For various seismic phases it can calculate:

  • arrival times
  • ray paths
  • reflection and transmission coefficients
  • take-off and incidence angles
  • geometrical spreading factors

Computations are done for a spherical earth. Cake can either be run as a command line tool or used as a Python module. Both is demonstrated in the examples below.

Invocation

cake <subcommand> [options]

Subcommands:

print

get information on model/phase/material properties

arrivals

print list of phase arrivals

paths

print ray path details

plot-xt

plot traveltime vs distance curves

plot-xp

plot ray parameter vs distance curves

plot-rays

plot ray propagation paths

plot

plot combination of ray and traveltime curves

plot-model

plot velocity model

list-models

list builtin velocity models

list-phase-map

show translation table for classic phase names

simplify-model

create a simplified version of a layered model

scatter

show details about scattering at model interfaces

To get further help and a list of available options for any subcommand run:

cake <subcommand> --help

Options

Each subcommand has its own set of options. Use cake <subcommand> --help to see which of the following options apply to any of the subcommands listed above.

Phases:

Seismic phase arrivals may be either specified as traditional phase names (e.g. P, S, PP, PcP, …) or in Cake’s own syntax which is more powerful. Use the --classic option, for traditional phase names. Use the --phase option if you want to define phases in Cake’s syntax.

--phase=PHASE1,PHASE2,..., --phases=PHASE1,PHASE2,...

Comma separated list of seismic phases in Cake’s syntax.

The definition of a seismic propagation path in Cake’s phase syntax is a string consisting of an alternating sequence of legs and knees.

A leg represents seismic wave propagation without any conversions, encountering only super-critical reflections. Legs are denoted by P, p, S, or s. The capital letters are used when the take-off of the leg is in a downward direction, while the lower case letters indicate a take-off in an upward direction.

A knee is an interaction with an interface. It can be a mode conversion, a reflection, or propagation as a headwave or diffracted wave.

  • conversion is simply denoted as: (INTERFACE) or DEPTH
  • upperside reflection: v(INTERFACE) or vDEPTH
  • underside reflection: ^(INTERFACE) or ^DEPTH
  • normal kind headwave or diffracted wave: v_(INTERFACE) or v_DEPTH

The interface may be given by name or by depth: INTERFACE is the name of an interface defined in the model, DEPTH is the depth of an interface in [km] (the interface closest to that depth is chosen). If two legs appear consecutively without an explicit knee, surface interaction is assumed.

The preferred standard interface names in cake are conrad, moho, cmb (core-mantle boundary), and icb (inner core boundary).

The phase definition may end with a backslash \, to indicate that the ray should arrive at the receiver from above instead of from below. It is possible to restrict the maximum and minimum depth of a leg by appending <(INTERFACE) or <DEPTH or >(INTERFACE) or >DEPTH after the leg character, respectively.

--classic=PHASE1,PHASE2,...

Comma separated list of seismic phases in classic nomenclature. Run cake list-phase-map for a list of available phase names.

Model:

--model=(NAME or FILENAME)

Use builtin model named NAME or user model from file FILENAME. By default, the “ak135-f-continental.m” model is used. Run cake list-models for a list of builtin models.

--format=FORMAT

Set model file format (available: nd, hyposat; default: nd).

--crust2loc=LAT,LON

Set model from CRUST2.0 profile at location (LAT,LON).

Source-receiver geometry:

--sdepth=FLOAT

Source depth [km] (default: 0)

--rdepth=FLOAT

Receiver depth [km] (default: 0)

--distances=DISTANCES

Surface distances as start:stop:n or dist1,dist2,... [km]

Material:

An isotropic elastic material may be specified by giving a combination of some of the following options.

--vp=FLOAT

P-wave velocity [km/s]

--vs=FLOAT

S-wave velocity [km/s]

--rho=FLOAT

density [g/cm**3]

--qp=FLOAT

P-wave attenuation Qp (default: 1456)

--qs=FLOAT

S-wave attenuation Qs (default: 600)

--poisson=FLOAT

Poisson ratio

--lambda=FLOAT

Lame parameter lambda [GPa]

--mu=FLOAT

Shear modulus [GPa]

--qk=FLOAT

Bulk attenuation Qk

--qmu=FLOAT

Shear attenuation Qmu

General:

-h, --help

Show help message and exit.

--vred=FLOAT

Velocity for time reduction in plot [km/s]

--degrees

Distances are in [deg] instead of [km], velocities in [deg/s] instead of [km/s].

--accuracy=MAXIMUM_RELATIVE_RMS

Set accuracy for model simplification.

--slowness=FLOAT

Select surface slowness [s/km] (default: 0)

--interface=(NAME or DEPTH)

Name or depth [km] of interface to select

Command line examples

Plot P and p phases

Ten receiver distances ranging from 100 km to 1000 km and a source depth of 10km.

cake plot-rays --crust2loc=45,10 --phases=P,p --sdepth=10 --distances=100:1000:10
../../_images/cake_plot_example.png

The option --crust2loc refers to the pyrocko.crust2x2 module and expects latitude and longitude of the source location.

Some water multiples

Receivers may be at any depth. Arbitrary reflection/conversion histories may be choosen.

cake plot-rays --sdepth=15 --distances=10 --rdepth=4.443 --crust2loc=0,0 \
               --phase='pP\,pPv3pP\,pPv3pPv3pP\,p'
../../_images/cake_plot_example_2.png

To print arrival times and other ray parameters, replace plot-rays with arrivals in the command line above.

> cake arrivals --sdepth=15 --distances=10 --rdepth=4.443 --crust2loc=0,0 \
              --phase='pP\,pPv3pP\,pPv3pPv3pP\,p'

slow    dist  time   take inci effi spre phase             used
s/km    km    s      deg  deg  %    %
----------------------------------------------------------------------------
0.09711 10.00 2.3147  128 10.6 58.7  103 p                 (p)
0.09099 10.00 8.1792  132 97.8 49.2  725 pP\               (p^0P\)
0.08461 10.00 14.052  136 97.3 8.03  729 pPv3pP\           (p^0Pv4.443p^0P\)
0.07835 10.00 19.931  140 96.8 1.32  710 pPv3pPv3pP\       (p^0Pv4.443p^0Pv4.443p^0P\)

Classic phase names

To use classic phase names, use the --classic option:

cake plot-rays --classic=Pdiff,PKP,PKIKP --distances=110:150:5 --degrees
../../_images/cake_plot_example_3.png

Model plots

cake plot-model --model=prem-no-ocean.m
../../_images/cake_plot_example_4.png

Cake phases

It is possible to see the exact definition of a phase using cake print ...:

> cake print --classic=Pg
Phase definition "P<(moho)":
 - P mode propagation, departing downward (may not propagate deeper than interface moho)
 - arriving at target from below
Phase definition "p<(moho)":
 - P mode propagation, departing upward (may not propagate deeper than interface moho)
 - arriving at target from below

This tells us that the classic Pg phase is represented with two Cake style phase definitions, one for downgoing and one for upgoing takeoff direction and that there is a constraint on maximum depth.

Here’s another example to illustrate why cake needs its special phase definition syntax:

> cat >waveguide.nd <<EOF
0 4 2.3  2.6
1 3 1.73 2.6
2 4 2.3  2.6
EOF
> cake plot-rays --phases='P,p,P\,p\' --sdepth=0.5 --rdepth=1.5 --distances=3,5 \
                 --model=waveguide.nd
../../_images/cake_plot_example_5.png

Material calculator

Cake can also be used to convert between different material parameters:

> cake print --vp=5 --poisson=0.25
P wave velocity     [km/s]    :            5
S wave velocity     [km/s]    :      2.88675
P/S wave vel. ratio           :      1.73205
Lame lambda         [GPa]     :      21.6667
Lame shear modulus  [GPa]     :      21.6667
Poisson ratio                 :         0.25
Bulk modulus        [GPa]     :      36.1111
Young's modulus     [GPa]     :      54.1667
Rayleigh wave vel.  [km/s]    :      2.65408
Density             [g/cm**3] :          2.6
Qp                            :         1350
Qs = Qmu                      :          600
Qk                            :          inf

Energy scatter at interface

The scatter subcommand may be used to see how much energy (in percent) is transmitted through or reflected by an interface for any given surface slowness (P-SV case):

> cake scatter --interface=moho --slowness=0.0
interface "moho" (35 km)

             4.349       3.209                     95.65       96.79
  \P         /P      \S  /S                        /P          /S
  ----------------   ----------------   ----------------   ----------------
             \P          \S             /P         \P      /S  \S
             95.65       96.79                     4.349       3.209



> cake scatter --interface=moho --slowness=0.15
interface "moho" (35 km)

      3.899  92.69       1.859  3.899       94.24  3.411
  \P  /S     /P      \S  /S     /P          /S     /P
  ----------------   ----------------   ----------------
      \S                 \S             /S  \S
      3.411              94.24              2.347

Python script examples

Calculate P-phase arrivals

The following Python script calculates arrival times for the P-phase emitted by an event in a depth of 300km.

'''
Calculate P-phase arrivals.
'''
from __future__ import print_function
from pyrocko import cake
import numpy as num

km = 1000.

# Load builtin 'prem-no-ocean' model (medium resolution)
model = cake.load_model('prem-no-ocean.m')

# Source depth [m].
source_depth = 300. * km

# Distances as a numpy array [deg].
distances = num.linspace(1500, 3000, 16)*km * cake.m2d

# Define the phase to use.
Phase = cake.PhaseDef('P')

# calculate distances and arrivals and print them:
print('distance [km]      time [s]')
for arrival in model.arrivals(distances, phases=Phase, zstart=source_depth):
    print('%13g %13g' % (arrival.x*cake.d2m/km, arrival.t))