[Emacs-diffs] /srv/bzr/emacs/trunk r103161: calc.texi (Logarithmic Units): New section

[Jay Belanger]

------------------------------------------------------------
revno: 103161
committer: Jay Belanger <address@hidden>
branch nick: trunk
timestamp: Sun 2011-02-06 19:35:09 -0600
message:
  calc.texi (Logarithmic Units): New section
modified:
  doc/misc/ChangeLog
  doc/misc/calc.texi

=== modified file 'doc/misc/ChangeLog'
--- a/doc/misc/ChangeLog        2011-02-06 00:25:41 +0000
+++ b/doc/misc/ChangeLog        2011-02-07 01:35:09 +0000
@@ -1,3 +1,7 @@
+2011-02-07  Jay Belanger  <address@hidden>
+
+       * calc.texi (Logarithmic Units): New section.
+
 2011-02-05  Teodor Zlatanov  <address@hidden>
 
        * gnus-overrides.texi: Renamed from overrides.texi and all the relevant

=== modified file 'doc/misc/calc.texi'
--- a/doc/misc/calc.texi        2011-01-25 04:08:28 +0000
+++ b/doc/misc/calc.texi        2011-02-07 01:35:09 +0000
@@ -27675,6 +27675,7 @@
 * The Units Table::
 * Predefined Units::
 * User-Defined Units::
+* Logarithmic Units::
 @end menu
 
 @node Basic Operations on Units, The Units Table, Units, Units
@@ -28036,7 +28037,7 @@
 
 @c Describe angular units, luminosity vs. steradians problem.
 
address@hidden User-Defined Units,  , Predefined Units, Units
address@hidden User-Defined Units, Logarithmic Units, Predefined Units, Units
 @section User-Defined Units
 
 @noindent
@@ -28120,6 +28121,249 @@
 is replaced by the new set.  (@xref{General Mode Commands}, for a way to
 tell Calc to use a different file for the Calc init file.)
 
address@hidden Logarithmic Units,  , User-Defined Units, Units
address@hidden Logarithmic Units
+
+The units @code{dB} (decibels) and @code{Np} (nepers) are logarithmic
+units which are typically manipulated differently than standard units.
+Calc provides commands to work with these logarithmic units.
+
+Decibels and nepers are used to measure power quantities as well as 
+field quantities (quantities whose squares are proportional to power).
+The decibel and neper values of a quantity are relative to
+a reference quantity; for example, the decibel value of a sound
+pressure level of 
address@hidden @math{60 uPa}
address@hidden @math{60 \mu{\rm Pa}}
+relative to 
address@hidden @math{20 uPa}
address@hidden @math{20 \mu{\rm Pa}}
+(the threshhold of human hearing) is 
address@hidden @math{20 log10(60 uPa/ 20 uPa) dB = 20 log10(3) dB},
address@hidden  @math{20 \log_{10}(60 \mu{\rm Pa}/20 \mu{\rm Pa}) {\rm dB} =
+20 \log_{10}(3) {\rm dB}},
+which is about 
address@hidden @math{9.54 dB}.
address@hidden @math{9.54 {\rm dB}}.
+Note that in taking the ratio, the original units cancel and so these
+logarithmic units are dimensionless. 
+
address@hidden calc-logunits-power-reference
address@hidden calc-logunits-field-reference
+The Calc commands for the logarithmic units assume that power quantities
+are being used unless the @kbd{H} prefix is used, in which case they assume 
that 
+field quantities are being used.  For power quantities, Calc uses 
address@hidden @math{1 mW} 
address@hidden @math{1 {\rm mW}}
+as the default reference quantity; this default can be changed by changing 
+the value of the customizable variable
address@hidden (@pxref{Customizing Calc}).
+For field quantities, Calc uses 
address@hidden @math{20 uPa} 
address@hidden @math{20 \mu{\rm Pa}}
+as the default reference quantity; this is the value used in acoustics
+which is where decibels are commonly encountered.  This default can be
+changed by changing the value of the customizable variable
address@hidden (@pxref{Customizing Calc}).  A
+non-default reference quantity will be read from the stack if the
+capital @kbd{O} prefix is used.
+
+The decibel level of a power 
address@hidden @math{P1},
address@hidden @math{P_1},
+relative to a reference power 
address@hidden @math{P0},
address@hidden @math{P_0},
+is defined to be
address@hidden @math{10 log10(P1/P0) dB}.
address@hidden @math{10 \log_{10}(P_{1}/P_{0}) {\rm dB}}.
+(The factor of 10 is because a decibel, as its name implies, is
+one-tenth of a bel. The bel, named after Alexander Graham Bell, was
+considered to be too large of a unit and was effectively replaced by
+the decibel.)  If @math{F} is a field quantity with power
address@hidden F^2}, then a reference quantity of 
address@hidden @math{F0}
address@hidden @math{F_0}
+would correspond to a power of 
address@hidden @math{P0=k F0^2}.
address@hidden @math{P_{0}=kF_{0}^2}.
+If
address@hidden @math{P1=k F1^2},
address@hidden @math{P_{1}=kF_{1}^2},
+then
+
address@hidden
address@hidden 
+10 log10(P1/P0) = 10 log10(F1^2/F0^2) = 20 log10(F1/F0).
address@hidden example
address@hidden ifnottex
address@hidden
+$$ 10 \log_{10}(P_1/P_0) = 10 \log_{10}(F_1^2/F_0^2) = 20
+\log_{10}(F_1/F_0)$$
address@hidden tex
+
address@hidden
+In order to get the same decibel level regardless of whether a field
+quantity or the corresponding power quantity is used,  the decibel
+level of a field quantity 
address@hidden @math{F1},
address@hidden @math{F_1}, 
+relative to a reference 
address@hidden @math{F0},
address@hidden @math{F_0}, 
+is defined as
address@hidden @math{20 log10(F1/F0) dB}.
address@hidden @math{20 \log_{10}(F_{1}/F_{0}) {\rm dB}}.
+
+Nepers (named after John Napier, who is credited with inventing the
+logarithm) are similar to bels except they use natural logarithms instead
+of common logarithms.  The neper level of a power 
address@hidden @math{P1},
address@hidden @math{P_1},
+relative to a reference power 
address@hidden @math{P0},
address@hidden @math{P_0},
+is
address@hidden @math{(1/2) ln(P1/P0) Np}.
address@hidden @math{(1/2) \ln(P_1/P_0) {\rm Np}}.
+The neper level of a field 
address@hidden @math{F1},
address@hidden @math{F_1},
+relative to a reference field
address@hidden @math{F0},
address@hidden @math{F_0},
+is
address@hidden @math{ln(F1/F0) Np}.
address@hidden @math{\ln(F_1/F_0) {\rm Np}}.
+
address@hidden l q
address@hidden calc-logunits-quantity
address@hidden powerquant
address@hidden fieldquant
+The @kbd{l q} (@code{calc-logunits-quantity}) address@hidden
+command computes the power quantity corresponding to a given number of
+logarithmic units. With the capital @kbd{O} prefix, @kbd{O l q}, the
+reference level will be read from the top of the stack. (In an
+algebraic formula, @code{powerquant} can be given an optional second
+argument which will be used for the reference level.) For example, 
address@hidden dB @key{RET} l q} will return @code{100 mW}; 
address@hidden dB @key{RET} 4 W @key{RET} O l q} will return @code{400 W}.   
+The @kbd{H l q} address@hidden command behaves like @kbd{l q} but
+computes field quantities instead of power quantities.
+
address@hidden l d
address@hidden calc-logunits-dblevel
address@hidden dbpowerlevel
address@hidden dbfieldlevel
address@hidden l n
address@hidden calc-logunits-nplevel
address@hidden nppowerlevel
address@hidden npfieldlevel
+The @kbd{l d} (@code{calc-logunits-dblevel}) address@hidden
+command will compute the decibel level of a power quantity using the
+default reference level; @kbd{H l d} address@hidden will
+compute the decibel level of a field quantity.  The commands @kbd{l n} 
+(@code{calc-logunits-nplevel}) address@hidden and @kbd{H l n} 
address@hidden will similarly compute neper levels.  With the
+capital @kbd{O} prefix these commands will read a reference level
+from the stack; in an algebraic formula the reference level can be
+given as an optional second argument.
+
address@hidden l +
address@hidden calc-logunits-add
address@hidden lupoweradd
address@hidden lufieldadd
address@hidden l -
address@hidden calc-logunits-sub
address@hidden lupowersub
address@hidden lufieldsub
address@hidden l *
address@hidden calc-logunits-mul
address@hidden lupowermul
address@hidden lufieldmul
address@hidden l /
address@hidden calc-logunits-div
address@hidden lupowerdiv
address@hidden lufielddiv
+The sum of two power or field quantities doesn't correspond to the sum
+of the corresponding decibel or neper levels.  If the powers
+corresponding to decibel levels 
address@hidden @math{D1} 
address@hidden @math{D_1} 
+and 
address@hidden @math{D2} 
address@hidden @math{D_2} 
+are added, the corresponding decibel level ``sum'' will be 
+
address@hidden
address@hidden
+  10 log10(10^(D1/10) + 10^(D2/10)) dB.
address@hidden example
address@hidden ifnottex
address@hidden
+$$ 10 \log_{10}(10^{D_1/10} + 10^{D_2/10}) {\rm dB}.$$
address@hidden tex
+
address@hidden
+When field quantities are combined, it often means the 
+corresponding powers are added and so the above formula might be used.  
+In acoustics, for example, the decibel sound pressure level is defined
+using the field formula but the sound pressure levels are combined
+as the sound power levels, and so the above formula should be used.  If 
+two field quantities themselves are added, the new decibel level will be 
+
+
address@hidden
address@hidden
+  20 log10(10^(D1/20) + 10^(D2/20)) dB.
address@hidden example
address@hidden ifnottex
address@hidden
+$$ 20 \log_{10}(10^{D_1/20} + 10^{D_2/20}) {\rm dB}.$$
address@hidden tex
+
address@hidden
+If the power corresponding to @math{D} dB is multiplied by a number @math{N},
+then the corresponding decibel level will be
+
address@hidden
address@hidden
+  D + 10 log10(N) dB,
address@hidden example
address@hidden ifnottex
address@hidden
+$$ D + 10 \log_{10}(N) {\rm dB},$$
address@hidden tex
+
address@hidden
+if a field quantity is multiplied by @math{N} the corresponding decibel level
+will be 
+
address@hidden
address@hidden
+  D + 20 log10(N) dB.
address@hidden example
address@hidden ifnottex
address@hidden
+$$ D + 20 \log_{10}(N) {\rm dB}.$$
address@hidden tex
+
address@hidden
+There are similar formulas for combining nepers.  
+The @kbd{l +} (@code{calc-logunits-add}) address@hidden command
+will ``add'' two logarithmic unit power levels this way; with the
address@hidden prefix, @kbd{H l +} address@hidden will add logarithmic
+unit field levels.  Similarly, logarithmic units can be
+``subtracted'' with @kbd{l -} (@code{calc-logunits-sub}) 
address@hidden or @kbd{H l -} address@hidden 
+The @kbd{l *} (@code{calc-logunits-mul}) address@hidden 
+and @kbd{H l *} address@hidden commands will ``multiply''
+a logarithmic unit by a number; the @kbd{l /}
+(@code{calc-logunits-divide})  address@hidden and  
address@hidden l /} address@hidden commands will ``divide'' a
+logarithmic unit by a number. Note that the reference quantities don't
+play a role in this arithmetic. 
+
 @node Store and Recall, Graphics, Units, Top
 @chapter Storing and Recalling
 
@@ -35225,6 +35469,19 @@
 and @code{calc-embedded-open-close-plain-alist}.
 @end defvar
 
address@hidden  calc-logunits-power-reference
address@hidden calc-logunits-field-reference
+See @ref{Logarithmic address@hidden
+The variables @code{calc-logunits-power-reference} and
address@hidden are unit expressions (written as
+strings) which Calc will use as reference quantities for logarithmic
+units.
+
+The default value of @code{calc-logunits-power-reference} is @code{"mW"}
+and the default value of @code{calc-logunits-field-reference} is
address@hidden"20 uPa"}.  
address@hidden defvar
+
 @defvar calc-highlight-selections-with-faces
 @defvarx calc-selected-face
 @defvarx calc-nonselected-face
@@ -35873,6 +36130,28 @@
 @r{    v x@:    I k T   @:             @:        @:ltpt@:(x,v)}
 
 @c
address@hidden    a b@:      l +   @:             @:     2  @:lupoweradd@:(a,b)}
address@hidden    a b@:    H l +   @:             @:     2  @:lufieldadd@:(a,b)}
address@hidden    a b@:      l -   @:             @:     2  @:lupowersub@:(a,b)}
address@hidden    a b@:    H l -   @:             @:     2  @:lufieldsub@:(a,b)}
address@hidden    a b@:      l *   @:             @:     2  @:lupowermul@:(a,b)}
address@hidden    a b@:    H l *   @:             @:     2  @:lufieldmul@:(a,b)}
address@hidden    a b@:      l /   @:             @:     2  @:lupowerdiv@:(a,b)}
address@hidden    a b@:    H l /   @:             @:     2  @:lufielddiv@:(a,b)}
address@hidden      a@:      l d   @:             @:     1  @:dbpowerlevel@:(a)}
address@hidden    a b@:    O l d   @:             @:     2  
@:dbpowerlevel@:(a,b)}
address@hidden      a@:    H l d   @:             @:     1  @:dbfieldlevel@:(a)}
address@hidden    a b@:  O H l d   @:             @:     2  
@:dbfieldlevel@:(a,b)}
address@hidden      a@:      l n   @:             @:     1  @:nppowerlevel@:(a)}
address@hidden    a b@:    O l n   @:             @:     2  
@:nppowerlevel@:(a,b)}
address@hidden      a@:    H l n   @:             @:     1  @:npfieldlevel@:(a)}
address@hidden    a b@:  O H l n   @:             @:     2  
@:npfieldlevel@:(a,b)}
address@hidden      a@:      l q   @:             @:     1  @:powerquant@:(a)}
address@hidden    a b@:    O l q   @:             @:     2  @:powerquant@:(a,b)}
address@hidden      a@:    H l q   @:             @:     1  @:fieldquant@:(a)}
address@hidden    a b@:  O H l q   @:             @:     2  @:fieldquant@:(a,b)}
+
address@hidden
 @r{       @:      m a   @:             @: 12,13  @:calc-algebraic-mode@:}
 @r{       @:      m d   @:             @:        @:calc-degrees-mode@:}
 @r{       @:      m e   @:             @:        
@:calc-embedded-preserve-modes@:}