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

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).

--sdepth=FLOAT

Source depth [km] (default: 0)

--rdepth=FLOAT

--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
```

The option `--crust2loc` refers to the `pyrocko.dataset.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'
```

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
```

Model plots¶

```cake plot-model --model=prem-no-ocean.m
```

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
```

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 pyrocko import cake
import numpy as num

km = 1000.

# Load builtin 'prem-no-ocean' model (medium resolution)

# 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))
```