How We Use the BBP Simulation API

What This Page Covers

Most of what Intensity Lab shows you is observational: USGS ShakeMap tells us what instruments actually recorded, and we interpolate that to the places people live. The animations are different. To shake a table you need a time series — ground position sampled hundreds of times a second — and a ShakeMap gives you a single peak value per site, not a wiggle.

So for qualifying earthquakes we buy that time series. Intensity Lab is a customer of bbpservices.net, which runs the SCEC Broadband Platform as a metered web API. We do not run the simulation ourselves. We describe the earthquake, name the places we care about, and receive seismograms. This page walks through that exchange.

The Whole Exchange, at a Glance

One simulation covers every site for an event, and one event costs exactly one job — both renderers of the same place read the same waveform.

Step 1 — The Source, from USGS

A simulation needs a fault, not a dot on a map. USGS gives us the earthquake's magnitude, epicenter and depth, and — when seismologists have published one — a moment tensor: the orientation of the fault that slipped, as strike (compass direction), dip (tilt) and rake (slip direction).

From magnitude we estimate how big the rupture was, using the Wells & Coppersmith (1994) regressions for subsurface rupture length and width. The fault plane is centred on the epicenter, with the hypocenter placed mid-way down-dip. A random seed is derived deterministically from the USGS event id, so re-running the same earthquake produces the same waveform rather than a new roll of the dice.

An honest caveat. A moment tensor always describes two mathematically equivalent fault planes, and nothing in the tensor itself says which one actually ruptured. We take the first plane USGS publishes. For most events either choice gives a similar answer at the distances we care about, but it is an assumption rather than a measurement.

Step 2 — Choosing the Sites

A BBP job asks for specific places. We send two kinds, and which ones depend on the animations an event has earned:

Gazetteer sites — a real populated place from our gazetteer. For the main animation this is the closest city that felt at least moderate shaking, so the scene is somewhere a viewer can place on a map.
Decay sites — three virtual points at 5, 50 and 100 km from the epicenter along a bearing toward a reference city. These are not towns; they exist so the four-panel decay animation can show the same earthquake weakening with distance, which is the single clearest way to see that intensity is about where you are, not just how big the earthquake was.

The list is de-duplicated before it is sent. Since one site can have two animations (the standard scene and the cartoon-kitchen scene), the same coordinates would otherwise appear twice — the same ground motion, billed twice.

Step 3 — Choosing the Method and the Region

The Broadband Platform implements several simulation methods, each contributed by a different research group. Intensity Lab requests GP (Graves & Pitarka) by default: a hybrid that computes long-period motion deterministically from wave propagation and short-period motion stochastically, then joins them. It is the most broadly validated method in the platform across the magnitude range we animate.

A method also needs a velocity model — a description of how seismic waves travel through the crust in that part of the world. These are regional (Los Angeles Basin, Northern California, Central California and others), and only the ones actually installed on the BBP host can be used. We ask the service which regions it currently serves, then pick the one whose native extent contains the epicenter. If none does, we pick the geographically nearest installed model and mark the result approximate — a nearby crustal model is a far better description than a distant one.

Why a magnitude floor. Simulation is reserved for events of roughly M5 and above. Below that the shaking is rarely strong enough to animate meaningfully, and the cost of a physics run is not repaid by what you would see.

Step 4 — What the Request Looks Like

Everything above is assembled into a single job spec and posted to the API. It has three parts:

Requests are authenticated with an API key tied to an Intensity Lab account, and the job is metered — the service prices it from the same rate table its cost estimator quotes, so an estimate and the bill cannot disagree.

Step 5 — Vs30 and the Site Term

Two houses the same distance from the same earthquake can shake very differently depending on what they stand on. Soft sediment amplifies shaking; hard rock does not. The standard measure is Vs30 — the average speed of shear waves through the top 30 metres, in metres per second. Lower is softer, and softer usually means stronger shaking.

We resolve Vs30 through the same service, which queries UCVM (the Unified Community Velocity Model) — the community's assembled knowledge of California's subsurface, including detailed geology-based maps. Where UCVM has no coverage, the value falls back to a regional estimate derived from topography, and finally to 760 m/s, the reference rock value.

Worth knowing: 760 m/s is both a perfectly legitimate reading for a rock site and the value we fall back to when nothing better is available. On the event pages we label which source each site's Vs30 came from, so the two cases can be told apart.

Step 6 — What Comes Back

The job runs on the service's own compute — minutes for a small scenario, longer for a large one — and we poll until it reaches a terminal state. What we collect is a set of acceleration seismograms, one per site: a plain-text time series with a time column and three components (north–south, east–west, up–down) in cm/s². Velocity traces come back alongside them.

Acceleration is what the ground does; to move a table in a 3-D scene we need position. So the pipeline integrates twice — acceleration to velocity to displacement — high-pass filtering at each stage, because a small constant error in acceleration becomes a large drift in position if it is integrated twice unchecked. The result drives the animation directly: the floor of the scene follows the recorded ground, and everything on the table responds through ordinary rigid-body physics.

Each event's waveforms are cached, so re-rendering an animation — or rendering the same place in a second visual style — never repeats the simulation.

When Simulation Isn't Available

Every step above can fail: the earthquake may be below the magnitude floor, outside the regions the service has installed, or the run itself may not finish. None of that stops an animation. The pipeline falls back to synthesising ground motion from the ShakeMap peak acceleration using a standard stochastic model, which produces plausible shaking of the right amplitude and duration even though it is not a physics simulation of that rupture.

The distinction matters, so we track it per animation rather than hiding it: an animation built from a simulated seismogram and one built from synthesised motion are different products, and only the first is a statement about the physics of a particular earthquake.

Physics Animation (Blender) — what happens to the waveform once it arrives.
Data Sources — where the USGS event information comes from.
ShakeMap vs. GMPE Comparison — the other independent estimate of shaking, and how Vs30 enters it.
API & Services — the external services Intensity Lab depends on.