Units

Determining the physical units of inputs and outputs in Salvus requires understanding which interpretation of the governing equations is chosen. Salvus supports several physically consistent interpretations for the scalar acoustic potential in purely acoustic simulations, and a unique one when acoustic and elastic physics are coupled. This page lists all supported interpretations, how to translate saved fields to physically meaningful quantities (pressure, particle velocity, displacement), and the special role of the coupled case.

In the elastic wave equation, all outputs are given in their canonical SI units. This is in contrast to the acoustic case, where the units depend on the chosen interpretation of the scalar field, typically some potential. Note that in coupled acoustic-elastic simulations, only one interpretation is allowed.

Acoustic simulations

The strong form we solve is written in a unified way as

with density $\rho$, wave speed $c$, scalar potential $\phi$, and source term $f$. Different physical choices for the dimensions assigned to $\phi$ and $f$ lead to different practical post-processing steps. Salvus does not enforce a single convention for pure acoustic runs; you decide which table below applies.

Interpretation A: Volume Density Injection Rate Source

In the first interpretation, the source term represents a volumetric injection rate with units $[f]=\text{s}^{-1}$, one finds $[\phi]=\text{Pa}\,s$. To get pressure and particle velocity, use:

Interpretation B: Divergence of Force Density Source

Assume $f$ carries divergence of force density units $[f]=\text{N}\,\text{m}^{-4}$, we find $[\phi]=\text{kg}^2\,\text{m}^{-4}\,\text{s}^{-2}$. Then

Interpretation C: Dimensionless forces

Motivated by interface coupling (see below) we can assign $[\phi]=\text{kg}/\text{m}$. Plugging this into the same governing equation implies a dimensionless right hand side in the strong form (i.e., $[f]=1$). This means that the source term becomes a normalized monopole source strength. For more insight in this, see the section on conversions below. Practical consequences:

*Note that one could also output [phi_t] and then compute the gradient afterwards, but this is much more involved on unstructured meshes than taking the time derivative of the gradient field with e.g. a central difference (higher order) scheme.

Interpretation C is mandatory when coupling to elasticity; A and B are only valid in purely acoustic scenarios.

Choosing among A or B (pure acoustic): Pick the one aligned with how your source is specified physically. Need immediate pressure? Use A. Have a known force density history? Use B. Planning to share meshes with elastic physics? Use C from the start to avoid reinterpretation.

For full algorithmic details see our paper here. Additionally, a complete list of fields which can be output can be found in the documentation.

Source conversion formulas

It is common to have a source specified in one physical description and wish to implement it under a different interpretation (or eventually migrate to a coupled simulation). The relations below let you translate between a purely acoustic physical source description and the dimensionless right-hand side f used in the coupled convention (Interpretation C). Denote the coupled-form source term by f_c(t) (dimensionless) and the time variable by t.

Given one of the following physical source descriptions in a pure acoustic setting:

Each physical description corresponds to a way of injecting work or mass/volume change into the acoustic field. In the coupled Interpretation C, the governing equation has a dimensionless right-hand side, so any dimensional source must be rescaled to produce the correctly scaled potential $\phi$ with units $\text{kg}/\text{m}$. A volume injection rate $q(t)$ is (up to constants) the time derivative of a dimensionless monopole strength-hence we integrate once to obtain its cumulative effect. A localized pressure history $p(t)$ enters as an imposed normal stress; dividing by the bulk modulus proxy $\rho c^2$ yields a dimensionless amplitude consistent with $p = -\phi_{tt}$. Finally, a divergence of force density $g(t)$ is (in the pure-acoustic interpretations) the second time derivative of a monopole-like loading; recovering the dimensionless f_c therefore requires two time integrations (and detrending to remove integration constants). This mapping ensures that after substitution into the coupled equation, $\phi$ and its derivatives reproduce the originally intended physical pressure / traction and volume-change effects.

Conversely, once you have a dimensionless f_c(t) (coupled interpretation):

Implementation tips:

1. Always window the source time function so its value and its first derivative vanish near simulation start to avoid long-period artifacts.
2. Numerical differentiation/integration should use the native solver time step to avoid interpolation phase errors (or heavily supersampled signals).
3. After integration, remove any residual linear trend (detrending) to enforce zero mean; this prevents persistent offsets in φ.

Design guidance:

• Use Interpretation A if your physical source is naturally specified as a volume injection rate and you mainly care about pressure time series.
• Use Interpretation B if you have (or conceptually think in terms of) a known divergence of force density field.
• Use Interpretation C if you will ever couple to elasticity, or if you prefer pressure via a second derivative and a straightforward formula for normal displacement at interfaces.
• Converting previously archived A/B datasets to the coupled view can be done via the conversion tables by reconstructing f_c(t) and recomputing derived fields.

Elastic simulations

In the elastic case, Salvus solves the general elastic wave equation. For the analysis of units involved in the source term specifically, let's limit ourselves to purely elastic linear media. The strong form of this equation is:

Here $\rho$ is density, $\mathbf{u}$ is displacement, and $f$ represents an external forcing term. The time and space dependency of these last three terms is taken as implicit to simplify notation. $\mathbf{C}$ is a fourth-order tensor characterizing the stiffness of the medium, and the symbol $:$ denotes a contraction over adjacent indices.

In the elastic case, it is a little less flexible to substitute units of the applied force. Let's see what units are present in the equation when one defines $\mathbf{u}$ as displacement in meters:

Let's substitute these units into the equation, and figure out in what units the source term should be. In this exercise, we forego the dimensionalities of the quantities.

Simplifying and using $[\text{Pa}] = [\text{N} \cdot \text{m}^{-2}]$, where $\text{N}$ denotes force in units of Newtons gives:

So, finally using $[ \text{N} ] = [\text{kg} \cdot \text{m} \cdot \text{s}^{-2}]$:

Which dictates that our source term $f$ needs to be interpreted in the strong form as a source term with units $\text{N} \cdot \text{m}^{-3}$.

The units of point sources (e.g. VectorPoint3D)

One often desires point sources to be injected in a wavefield simulation. As a case study, we look at how to interpret the units of VectorPoint3D. The signature of creating this object is as follows:

Copy
class VectorPoint3D:
    def __init__(
        self,
        x: float,
        y: float,
        z: float,
        fx: float,
        fy: float,
        fz: float,
        ...
    ):
        ...

To know in what units the source_time_function $\text{stf}(t)$ of these sources should be interpreted, we start with the formulation of this point source $f$ as injected into the strong form:

$$ f(\mathbf{x}, t) = \text{stf}(t) \, \mathbf{F} \,\delta(\mathbf{x}) $$

In this definition, the vector $\mathbf{F} = [$fx, fy, fz$]$ allows one to orient (and scale) the source in any direction. The symbol $\delta$ indicates the (multidimensional) Dirac delta function.

The units of the Dirac delta function should be interpreted to collapse to dimensionless if integrated over its argument. In this case, we would integrate over three spatial coordinates, giving it the units $\text{m}^{-3}$. If now we interpret the orientation vector $\mathbf{F}$ as dimensionless, the units of $\text{stf}(t)$ are found in the following way:

Yielding that $\text{stf}(t)$ should be interpreted as Newtons when $\mathbf{F}$ is dimensionless. More generally, only the product $\text{stf}(t) \, \mathbf{F}$ is physically constrained: it must carry units of Newtons. How you split amplitude between the STF and $\mathbf{F}$ is a user choice (see the summary table below).

The units of moment tensor point sources (e.g. MomentTensorPoint3D)

Moment tensor sources are central to seismology. Unlike vector point sources, which represent monopole forces, moment tensor sources represent force couples (dipoles). As a case study, we look at how to interpret the units of MomentTensorPoint3D. The signature of creating this object is as follows:

Copy
class MomentTensorPoint3D:
    def __init__(
        self,
        x: float,
        y: float,
        z: float,
        mxx: float,
        myy: float,
        mzz: float,
        myz: float,
        mxz: float,
        mxy: float,
        ...
    ):
        ...

The six parameters mxx, ..., mxy are the independent components of the symmetric moment tensor $\mathbf{M}$ in Voigt notation. The symmetry $M_{ij} = M_{ji}$ reduces the nine tensor components to six independent ones.

A moment tensor point source enters the strong form of the elastic wave equation as the negative divergence of a localized stress-like tensor:

Physically, the gradient of the delta function represents a force couple: two equal and opposite point forces infinitesimally close together. The tensor $\mathbf{M}$ specifies the orientation and relative strength of these couples.

To determine the units of $\text{stf}(t)$, we need the units of $\partial_j \delta(\mathbf{x})$. We already established that $[\delta(\mathbf{x})] = \text{m}^{-3}$ in three dimensions. Its spatial derivative picks up one additional $\text{m}^{-1}$:

$$ [\partial_j \delta(\mathbf{x})] = \text{m}^{-4} $$

We showed earlier that the force density in the elastic strong form satisfies $[f_i] = \text{N} \cdot \text{m}^{-3}$. Interpreting $\mathbf{M}$ as a dimensionless orientation/scaling tensor:

Yielding:

$$ [\text{stf}(t)] = \text{N} \cdot \text{m} $$

The source time function of a moment tensor source should therefore be interpreted in units of Newton-meters (when $\mathbf{M}$ is dimensionless), i.e., the physical unit of seismic moment. This is consistent with the seismological convention where the scalar seismic moment $M_0$ has units of $\text{N} \cdot \text{m}$.

As with all elastic sources, only the product $\text{stf}(t) \cdot M_{ij}$ is physically constrained: it must carry units of $\text{N} \cdot \text{m}$. If the moment tensor components encode both a focal mechanism and a scalar amplitude, the STF may be correspondingly dimensionless.

Connection to seismic moment

In seismology, the moment tensor is often decomposed as:

where $M_0$ is the scalar seismic moment ($\text{N} \cdot \text{m}$), $m_{ij}$ is the unit-normalized mechanism tensor (with $|m_{ij}| \le 1$), and $s(t)$ is the normalized source time function (dimensionless, peak value 1). In Salvus's parameterization, setting the moment tensor weights to $m_{ij}$ and scaling the STF amplitude to $M_0$ reproduces this decomposition. Alternatively, one can absorb $M_0$ into the weights and use a unit-amplitude STF-only the product matters.

2-D vs 3-D

In 2-D, the simulation domain represents an infinite out-of-plane extent. Salvus uses a plane-strain approximation in 2-D, The 2-D Dirac delta satisfies $[\delta^{(2D)}(\mathbf{x})] = \text{m}^{-2}$, leading to $[\partial_j \delta^{(2D)}] = \text{m}^{-3}$. The force density constraint is unchanged ($\text{N} \cdot \text{m}^{-3}$), so:

$$ [\text{stf}(t)]_{\text{2D}} = \text{N} $$

A "2-D moment tensor" STF therefore has units of Newtons, not Newton-meters. Physically, this is the moment per unit out-of-plane length ($\text{N} \cdot \text{m} / \text{m} = \text{N}$). The same dimensional reduction applies to all 2-D sources: a 2-D point source is a 3-D line source extending infinitely in the out-of-plane direction.

Note that the different amplitude decay and dispersion relations are thus expected in 2-D vs. 3-D.

The units of vector gradient point sources (e.g. VectorGradientPoint3D)

The VectorGradientPoint3D source generalizes the moment tensor source by relaxing the symmetry constraint. Where a moment tensor has 6 independent components in 3-D (symmetric $M_{ij} = M_{ji}$), a vector gradient source has $d^2$ independent components (the full, generally non-symmetric, tensor $G_{ij}$)-giving 9 components in 3-D and 4 in 2-D:

Copy
class VectorGradientPoint3D:
    def __init__(
        self,
        x: float,
        y: float,
        z: float,
        gxx: float,
        gxy: float,
        gxz: float,
        gyx: float,
        gyy: float,
        gyz: float,
        gzx: float,
        gzy: float,
        gzz: float,
        ...
    ):
        ...

The injection mechanism is identical to the moment tensor case:

The unit analysis follows accordingly:

The antisymmetric part of $G_{ij}$ (i.e., $\frac{1}{2}(G_{ij} - G_{ji})$, which has no counterpart in the symmetric moment tensor) represents rotational force couples that produce a net torque but no net moment. This is useful for modeling certain types of dislocations, CLVD (compensated linear vector dipole) decompositions, or other non-double-couple source mechanisms.

Summary: STF units for elastic point sources

Salvus supports five source mechanisms: Scalar, ScalarGradient, Vector, MomentTensor, and VectorGradient. Of these, only Vector, MomentTensor, and VectorGradient are valid in elastic elements (the solver enforces this consistency check). The Scalar and ScalarGradient mechanisms are acoustic-only and their unit interpretations depend on which acoustic convention is chosen (see the acoustic section above). The table below collects the STF units for all three elastic point source types, in both 2-D and 3-D:

Salvus does not enforce a particular split between the STF and the spatial weights. Only their product $\text{stf}(t) \cdot w_k$ is physically meaningful, and it must carry the units listed in the table. The derivations above assume dimensionless weights for clarity, so that the STF alone carries the full physical amplitude. In practice, many users specify the weights in physical units (e.g., mxx in $\text{N} \cdot \text{m}$ for a 3-D moment tensor), in which case the STF is correspondingly dimensionless. Either convention is valid as long as it is applied consistently.

Note on interpretation dependence: unlike the acoustic case, where the units of the STF depend on which interpretation (A, B, or C) of the scalar potential $\phi$ is chosen, the elastic case has a unique state-variable convention: $\mathbf{u}$ is displacement in meters. There is no analogous freedom. The units listed above therefore hold unconditionally for any elastic simulation in SI units.

Coupled acoustic–elastic simulations

When an acoustic region adjoins an elastic region within the same simulation, the interface conditions uniquely determine the permissible scaling of the acoustic potential. Across any acoustic–elastic boundary with outward normal $\hat{n}$ (Nissen-Meyer et al., 2007, equation 46):

With elastic displacement $[\mathbf{u}] = \text{m}$ and stress $[\sigma_{nn}] = \text{Pa}$, these two relations force $[\phi]=\text{kg}/\text{m}$ and $p = -\phi_{tt}$. Thus only acoustic simulations' Interpretation C is consistent; A and B would break continuity. Practical recipe for coupled simulations:

1. Request phi_tt to obtain pressure: pressure = -phi_tt.
2. Request gradient-of-phi and multiply its components by 1/rho to get displacement components.
3. All elastic outputs retain their canonical SI units: displacement (m), velocity (m/s), stress / pressure (Pa), etc.

FAQ (Coupled)

Why is there a minus sign in $p = -\phi{tt}?_ The sign follows directly from the stress balance with our positive pressure convention; in the frequency domain $\phi_{tt} \rightarrow -\omega^2 \phi giving the expected 180° phase relative to $\phi$.

What are the units of the acoustic source term now? Dimensionless in the strong form; any physical forcing is mediated through traction continuity or is scaled so that resulting $\phi$ has $[\text{kg}/\text{m}]$.

Can I still use a volume injection rate source in a coupled run? No. That scaling would force inconsistent interface units.