Logarithmic scales

Left- or right-multiplying a pure number by a logarithmic "unit", whether dimensionful or dimensionless, is short-hand for constructing a logarithmic quantity.

Currently implemented are dB, B, dBm, dBV, dBu, dBμV, dBSPL, dBFS, cNp, Np.

One can also construct logarithmic quantities using the @dB, @B, @cNp, @Np macros to use an arbitrary reference level:

These macros are exported by default since empirically macros are defined less often than variables and generic functions. When using the macros, the levels are constructed at parse time. The scales themselves are callable as functions if you need to construct a level that way (they are not exported):

In calculating the logarithms, the log function appropriate to the scale in question is used (log10 for decibels, log for nepers).

There is an important difference in these two approaches to constructing logarithmic quantities. When we construct 0dBm, the power in mW is calculated and stored, resulting in a lossy floating-point conversion. This can be avoided by constructing 0 dBm as @dB 1mW/mW.

It is important to keep in mind that the reference level is just used to calculate the logarithms, and nothing more. When there is ambiguity about what to do, we fall back to the underlying linear quantities, paying no mind to the reference levels:

Addition will be discussed more later.

Note that logarithmic "units" can only multiply or be multiplied by pure numbers and linear units, not other logarithmic units or quantities. This is done to avoid issues with commutativity and associativity, e.g. 3*dB*m^-1 == (3dB)/m, but 3*m^-1*dB == (3m^-1)*dB does not make much sense. This is because dB acts more like a constructor than a proper unit.

The @dB and @Np macros will fail if either a dimensionless number or a ratio of dimensionless numbers is used. This is because the ratio could be of power quantities or of root-power quantities, leading to ambiguities. After all, usually it is the ratio that is dimensionless, not the numerator and denominator that make up the ratio. In some cases it may nonetheless be convenient to have a dimensionless reference level. By providing an extra Bool argument to these macros, you can explicitly choose whether the resulting ratio should be considered a "root-power" or "power" ratio. You can only do this for dimensionless numbers:

Note that dBFS is defined to represent amplitudes relative to 1 in dB, hence the custom display logic.

Also, you can of course use functions instead of macros:

Multiplying a dimensionless logarithmic quantity by a pure number acts as like it does for linear quantities:

Justification by example: consider the example of the exponential attenuation of a signal on a lossy transmission line. If the attenuation goes like , then the (power) attenuation in dB is . We see that the attenuation in dB is linear in length. For an attenuation constant of 3dB/m, we better calculate 6dB for a length of 2m.

Multiplying a dimensionful logarithmic quantity by a pure number acts differently than multiplying a gain/attenuation by a pure number. Since 0dBm == 1mW, we better have that 0dBm * 2 == 2mW, implying:

Logarithmic quantities can only be multiplied by pure numbers, linear units, or quantities, but not logarithmic "units" or quantities. When a logarithmic quantity is multiplied by a linear quantity, the logarithmic quantity is linearized and multiplication proceeds as usual:

The previous example returns a floating point value because in constructing the level 0 dBm, the power in mW is calculated and stored, entailing a floating point conversion. This can be avoided by constructing 0 dBm as @dB 1mW/mW:

We refer to a quantity with both logarithmic "units" and linear units as a mixed quantity. For mixed quantities, the numeric value associates with the logarithmic unit, and the quantity is displayed in a way that makes this explicit:

Mathematical operations are forwarded to the logarithmic part, so that for example, 100*((0dBm)/s) == (20dBm)/s. We allow linear units to commute with logarithmic quantities for convenience, though the association is understood (e.g. s^-1*(3dBm) == (3dBm)/s).

The behavior of multiplication is summarized in the following table, with entries marked by † indicating prohibited operations.

‡: 1/Hz * 3dB could be allowed, technically, but we throw an error if it’s unclear whether a quantity is a root-power or power quantity:

On the other hand, if it can be determined that a power quantity or root-power quantity is being multiplied by a gain, then the gain is interpreted as a power ratio or root-power ratio, respectively:

We can add logarithmic quantities without reference levels specified (Gains):

The numbers out front of the dB just add: when we talk about gain or attenuation, we work in logarithmic units so that we can add rather than multiply gain factors. The same behavior holds when we add a Gain to a Level or vice versa:

In the case where you have differing logarithmic scales for the Level and the Gain, the logarithmic scale of the Level is used for the result:

For logarithmic quantities with the same reference levels, the numbers out in front do not simply add:

This is because dBm represents a power, ultimately. If we have some amount of power and we double it, we’d better get roughly 3 dB more power. Note that the juxtaposition 20dBm will ensure that 20 dBm is constructed before multiplication by 2 in the above example. If you were to type 2*20*dBm, you’d get 40 dBm.

If the reference levels differ but both levels represent a power, we fall back to linear quantities:

i.e. 1.1 W.

Rules for addition are summarized in the following table, with entries marked by † indicating prohibited operations.

Notice that we disallow implicit conversions between dimensionless logarithmic quantities and real numbers. This is because the results can depend on promotion rules in addition to being ambiguous because of the root-power vs. power ratio issue. If 100 + 10dB were evaluated as 20dB + 10dB == 30dB, then we’d get 1000, but if it were evaluated as 100+10, we’d get 110.

Also, although it is possible in principle to add e.g. 20dB + 1Np, notice that we have not implemented that because it is unclear whether the result should be in nepers or decibels, and it is also unclear how to handle that question more generally as other logarithmic scales are introduced.

As alluded to earlier, conversions can be tricky because so-called logarithmic units are not units in the conventional sense.

You may use linear to convert to a linear scale when you have a Level or Quantity{<:Level} type. There is a fallback for Number, which just returns the number.

Linearizing a Quantity{<:Gain} or a Gain to a real number is ambiguous, because the real number may represent a ratio of powers or a ratio of root-power (field) quantities. We implement Unitful.uconvertp and Unitful.uconvertrp which may be thought of as disambiguated uconvert functions. There is a one argument version that assumes you are converting to a unitless number. These functions can take either a Gain or a Real so that they may be used somewhat generically.

This package displays logarithmic quantities using shorthand like dBm where available. This should probably not be done in polite company. To quote "Guide for the Use of the International System of Units (SI)," NIST Special Pub. 811 (2008):

The authorities say the reference level should always specified. In practice, this hasn’t stopped the use of dBm and the like on commercially available test equipment. Dealing with these units is unavoidable in practice. When no shorthand exists, we follow NIST’s advice in displaying logarithmic quantities: