Due to the variety of wave-equations and source-time functions one can use in Salvus Compute, the question of "which units are my results output in?" can be non-trivial. If you are interested in precisely determining the units of input and output, please read on.

Acoustic simulations

Within Salvus, we consider a formulation of the acoustic wave equation based on a scalar displacement potential. The strong form of this equation is:

ρ1c2t2ϕ=(ρ1ϕ)+f. \rho ^{-1} c ^{-2} \partial _t^2 \phi = \nabla \cdot (\rho ^{-1} \nabla \phi) + f.

Here ρ\rho represents density, cc is the speed of sound, and by definition the units of the state variable ϕ\phi are m2\text{m}^2. Depending on the units of our forcing term ff, physically useful units can be extracted from the solution as follows.

Source in units of Volume Density Injection Rate (s1\text{s}^{-1})

Desired outputExpressionField to saveFurther operations
Pressure (Nm2\text{N}\cdot \text{m}^{-2})ϕt\phi _t["phi_t"]None
Particle velocity (ms1m \cdot s^{-1})ϕρ1\nabla \phi \cdot \rho ^{-1}["gradient-of-phi"]Multiply by the inverse density

Source in units of Force Density (Nm3\text{N} \cdot \text{m}^{-3})

Desired outputExpressionField to saveFurther operations
Pressure (Nm2\text{N}\cdot \text{m}^{-2})ϕρ1\phi \cdot \rho^{-1}["phi"]Multiply by the inverse density
Particle velocity (ms1\text{m}\cdot s^{-1})ϕ  dtρ2\int \nabla \phi\;dt \cdot \rho ^{-2}["gradient-of-phi"]Multiply by the inverse density squared

For more information on the physical equations solved in Salvus, please check out our paper here. Additionally, a complete list of fields which can be output can be found in the documentation.

Elastic simulations

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

ρt2u=(C:u)+f. \rho \, \partial _t^2 \mathbf{u} = \nabla \cdot (\mathbf{C} : \nabla \mathbf{u}) + \mathbf{\mathcal{f}}.

Here ρ\rho is density, u\mathbf{u} is displacement and ff represents an external forcing term. The time and space dependency of these last three terms is taken as implicit to simplify notation. C\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 u\mathbf{u} as displacement in meters:

SymbolQuantity (Unit)
ρ\rhoDensity (kgm3\text{kg}\cdot\text{m}^{-3})
u\mathbf{u}Displacement (m\text{m})
C\mathbf{C}Elasticity (Pa\text{Pa})
t\partial_tTime derivative, variation per second (s1\text{s}^{-1})
\nablaSpatial derivative, variation per meter (m1\text{m}^{-1})

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.

[kgm3]t2[m]=([Pa]:[m])+f. [\text{kg} \cdot \text{m}^{-3}] \, \partial _t^2 [\text{m}] = \nabla \cdot ([\text{Pa}] : \nabla [\text{m}]) + \mathbf{\mathcal{f}}. \\ \\

Applying the space and time derivatives as [m1][\text{m}^{-1}] and [s1][\text{s}^{-1}] respectively, and dropping the vector and tensor operators as they don't influence the units:

[kgm3][ms2]=[m1]([Pa][mm1])+f. [\text{kg} \cdot \text{m}^{-3}] \, [\text{m} \cdot \text{s}^{-2}] = [\text{m}^{-1}] \left( [\text{Pa}] [\text{m} \cdot \text{m}^{-1}]\right) + \mathbf{\mathcal{f}}.

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

[kgms2m3]=[m1][Nm2]+f, [\text{kg}\cdot\text{m} \cdot \text{s}^{-2} \cdot \text{m}^{-3}] = [\text{m}^{-1}] \cdot [\text{N} \cdot \text{m}^{-2}] + \mathbf{\mathcal{f}},

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

[Nm3]=[Nm3]+f. [\text{N} \cdot \text{m}^{-3}] = [\text{N} \cdot \text{m}^{-3}] + \mathbf{\mathcal{f}}.

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

The units of vector point sources (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:

class VectorPoint3D(salvus.flow.simple_config.source._BaseSource):
    def __init__(
        x: float,
        y: float,
        z: float,
        fx: float,
        fy: float,
        fz: float,
        source_time_function: Optional[
        ] = None,
        rotation_on_input: Optional[Dict] = None,

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

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

In this definition, the vector F=[\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 m3\text{m}^{-3}. If now we interpret the orientation vector F\mathbf{F} as dimensionless, the units of stf(t)\text{stf}(t) are found in the following way:

[Nm3]=stf(t)[1][m3] [\text{N} \cdot \text{m}^{-3}] = \text{stf}(t) \cdot [ 1 ] \cdot [\text{m}^{-3}]

Yielding that stf(t)\text{stf}(t) should be interpreted as Newtons. Conversely, if F\mathbf{F} is not unit length, only the combination stf(t)F\text{stf}(t) \, \mathbf{F} should be interpreted as the exact Newtons injected in the wavefield simulation.