X-Git-Url: http://git.hcoop.net/bpt/emacs.git/blobdiff_plain/233ba4d924933cb56129bd7511e6137b7c0b8e3e..ce57c2fe307e2d866ff0a3c8e3cb4dcd722c4da1:/doc/misc/calc.texi diff --git a/doc/misc/calc.texi b/doc/misc/calc.texi index 755956a299..f732eff569 100644 --- a/doc/misc/calc.texi +++ b/doc/misc/calc.texi @@ -111,7 +111,7 @@ developing GNU and promoting software freedom.'' @end quotation @end copying -@dircategory Emacs +@dircategory Emacs misc features @direntry * Calc: (calc). Advanced desk calculator and mathematical tool. @end direntry @@ -27675,6 +27675,8 @@ begin with the @kbd{u} prefix key. * The Units Table:: * Predefined Units:: * User-Defined Units:: +* Logarithmic Units:: +* Musical Notes:: @end menu @node Basic Operations on Units, The Units Table, Units, Units @@ -28036,7 +28038,7 @@ really is unitless.) @c Describe angular units, luminosity vs. steradians problem. -@node User-Defined Units, , Predefined Units, Units +@node User-Defined Units, Logarithmic Units, Predefined Units, Units @section User-Defined Units @noindent @@ -28120,6 +28122,315 @@ was already a set of user-defined units in your Calc init file, it 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.) +@node Logarithmic Units, Musical Notes, User-Defined Units, Units +@section Logarithmic Units + +The units @code{dB} (decibels) and @code{Np} (nepers) are logarithmic +units which are 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); +these two types of quantities are handled slightly different from each +other. By default the Calc commands work as if power quantities are +being used; with the @kbd{H} prefix the Calc commands work as if field +quantities are being used. + +The decibel level of a power +@infoline @math{P1}, +@texline @math{P_1}, +relative to a reference power +@infoline @math{P0}, +@texline @math{P_0}, +is defined to be +@infoline @math{10 log10(P1/P0) dB}. +@texline @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 +@math{P=k F^2}, then a reference quantity of +@infoline @math{F0} +@texline @math{F_0} +would correspond to a power of +@infoline @math{P0=k F0^2}. +@texline @math{P_{0}=kF_{0}^2}. +If +@infoline @math{P1=k F1^2}, +@texline @math{P_{1}=kF_{1}^2}, +then + +@ifnottex +@example +10 log10(P1/P0) = 10 log10(F1^2/F0^2) = 20 log10(F1/F0). +@end example +@end ifnottex +@tex +$$ 10 \log_{10}(P_1/P_0) = 10 \log_{10}(F_1^2/F_0^2) = 20 +\log_{10}(F_1/F_0)$$ +@end tex + +@noindent +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 +@infoline @math{F1}, +@texline @math{F_1}, +relative to a reference +@infoline @math{F0}, +@texline @math{F_0}, +is defined as +@infoline @math{20 log10(F1/F0) dB}. +@texline @math{20 \log_{10}(F_{1}/F_{0}) {\rm dB}}. +For example, the decibel value of a sound pressure level of +@infoline @math{60 uPa} +@texline @math{60 \mu{\rm Pa}} +relative to +@infoline @math{20 uPa} +@texline @math{20 \mu{\rm Pa}} +(the threshhold of human hearing) is +@infoline @math{20 log10(60 uPa/ 20 uPa) dB = 20 log10(3) dB}, +@texline @math{20 \log_{10}(60 \mu{\rm Pa}/20 \mu{\rm Pa}) {\rm dB} = 20 \log_{10}(3) {\rm dB}}, +which is about +@infoline @math{9.54 dB}. +@texline @math{9.54 {\rm dB}}. +Note that in taking the ratio, the original units cancel and so these +logarithmic units are dimensionless. + +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 +@infoline @math{P1}, +@texline @math{P_1}, +relative to a reference power +@infoline @math{P0}, +@texline @math{P_0}, +is +@infoline @math{(1/2) ln(P1/P0) Np}. +@texline @math{(1/2) \ln(P_1/P_0) {\rm Np}}. +The neper level of a field +@infoline @math{F1}, +@texline @math{F_1}, +relative to a reference field +@infoline @math{F0}, +@texline @math{F_0}, +is +@infoline @math{ln(F1/F0) Np}. +@texline @math{\ln(F_1/F_0) {\rm Np}}. + +@vindex calc-lu-power-reference +@vindex calc-lu-field-reference +For power quantities, Calc uses +@infoline @math{1 mW} +@texline @math{1 {\rm mW}} +as the default reference quantity; this default can be changed by changing +the value of the customizable variable +@code{calc-lu-power-reference} (@pxref{Customizing Calc}). +For field quantities, Calc uses +@infoline @math{20 uPa} +@texline @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 +@code{calc-lu-field-reference} (@pxref{Customizing Calc}). A +non-default reference quantity will be read from the stack if the +capital @kbd{O} prefix is used. + +@kindex l q +@pindex calc-lu-quant +@tindex lupquant +@tindex lufquant +The @kbd{l q} (@code{calc-lu-quant}) [@code{lupquant}] +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{lupquant} can be given an optional second +argument which will be used for the reference level.) For example, +@code{20 dB @key{RET} l q} will return @code{100 mW}; +@code{20 dB @key{RET} 4 W @key{RET} O l q} will return @code{400 W}. +The @kbd{H l q} [@code{lufquant}] command behaves like @kbd{l q} but +computes field quantities instead of power quantities. + +@kindex l d +@pindex calc-db +@tindex dbpower +@tindex dbfield +@kindex l n +@pindex calc-np +@tindex nppower +@tindex npfield +The @kbd{l d} (@code{calc-db}) [@code{dbpower}] command will compute +the decibel level of a power quantity using the default reference +level; @kbd{H l d} [@code{dbfield}] will compute the decibel level of +a field quantity. The commands @kbd{l n} (@code{calc-np}) +[@code{nppower}] and @kbd{H l n} [@code{npfield}] 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. + +@kindex l + +@pindex calc-lu-plus +@tindex lupadd +@tindex lufadd +@kindex l - +@pindex calc-lu-minus +@tindex lupsub +@tindex lufsub +@kindex l * +@pindex calc-lu-times +@tindex lupmul +@tindex lufmul +@kindex l / +@pindex calc-lu-divide +@tindex lupdiv +@tindex lufdiv +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 +@infoline @math{D1} +@texline @math{D_1} +and +@infoline @math{D2} +@texline @math{D_2} +are added, the corresponding decibel level ``sum'' will be + +@ifnottex +@example + 10 log10(10^(D1/10) + 10^(D2/10)) dB. +@end example +@end ifnottex +@tex +$$ 10 \log_{10}(10^{D_1/10} + 10^{D_2/10}) {\rm dB}.$$ +@end tex + +@noindent +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 sound pressure level is a field quantity +and so the decibels are often 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 + +@ifnottex +@example + 20 log10(10^(D1/20) + 10^(D2/20)) dB. +@end example +@end ifnottex +@tex +$$ 20 \log_{10}(10^{D_1/20} + 10^{D_2/20}) {\rm dB}.$$ +@end tex + +@noindent +If the power corresponding to @math{D} dB is multiplied by a number @math{N}, +then the corresponding decibel level will be + +@ifnottex +@example + D + 10 log10(N) dB, +@end example +@end ifnottex +@tex +$$ D + 10 \log_{10}(N) {\rm dB},$$ +@end tex + +@noindent +if a field quantity is multiplied by @math{N} the corresponding decibel level +will be + +@ifnottex +@example + D + 20 log10(N) dB. +@end example +@end ifnottex +@tex +$$ D + 20 \log_{10}(N) {\rm dB}.$$ +@end tex + +@noindent +There are similar formulas for combining nepers. The @kbd{l +} +(@code{calc-lu-plus}) [@code{lupadd}] command will ``add'' two +logarithmic unit power levels this way; with the @kbd{H} prefix, +@kbd{H l +} [@code{lufadd}] will add logarithmic unit field levels. +Similarly, logarithmic units can be ``subtracted'' with @kbd{l -} +(@code{calc-lu-minus}) [@code{lupsub}] or @kbd{H l -} [@code{lufsub}]. +The @kbd{l *} (@code{calc-lu-times}) [@code{lupmul}] and @kbd{H l *} +[@code{lufmul}] commands will ``multiply'' a logarithmic unit by a +number; the @kbd{l /} (@code{calc-lu-divide}) [@code{lupdiv}] and +@kbd{H l /} [@code{lufdiv}] commands will ``divide'' a logarithmic +unit by a number. Note that the reference quantities don't play a role +in this arithmetic. + +@node Musical Notes, , Logarithmic Units, Units +@section Musical Notes + +Calc can convert between musical notes and their associated +frequencies. Notes can be given using either scientific pitch +notation or midi numbers. Since these note systems are basically +logarithmic scales, Calc uses the @kbd{l} prefix for functions +operating on notes. + +Scientific pitch notation refers to a note by giving a letter +A through G, possibly followed by a flat or sharp) with a subscript +indicating an octave number. Each octave starts with C and ends with +B and +@c increasing each note by a semitone will result +@c in the sequence @expr{C}, @expr{C} sharp, @expr{D}, @expr{E} flat, @expr{E}, +@c @expr{F}, @expr{F} sharp, @expr{G}, @expr{A} flat, @expr{A}, @expr{B} +@c flat and @expr{B}. +the octave numbered 0 was chosen to correspond to the lowest +audible frequency. Using this system, middle C (about 261.625 Hz) +corresponds to the note @expr{C} in octave 4 and is denoted +@expr{C_4}. Any frequency can be described by giving a note plus an +offset in cents (where a cent is a ratio of frequencies so that a +semitone consists of 100 cents). + +The midi note number system assigns numbers to notes so that +@expr{C_(-1)} corresponds to the midi note number 0 and @expr{G_9} +corresponds to the midi note number 127. A midi controller can have +up to 128 keys and each midi note number from 0 to 127 corresponds to +a possible key. + +@kindex l s +@pindex calc-spn +@tindex spn +The @kbd{l s} (@code{calc-spn}) [@code{spn}] command converts either +a frequency or a midi number to scientific pitch notation. For +example, @code{500 Hz} gets converted to +@code{B_4 + 21.3094853649 cents} and @code{84} to @code{C_6}. + + +@kindex l m +@pindex calc-midi +@tindex midi +The @kbd{l m} (@code{calc-midi}) [@code{midi}] command converts either +a frequency or a note given in scientific pitch notation to the +corresponding midi number. For example, @code{C_6} gets converted to 84 +and @code{440 Hz} to 69. + +@kindex l f +@pindex calc-freq +@tindex freq +The @kbd{l f} (@code{calc-freq}) [@code{freq}] command converts either +either a midi number or a note given in scientific pitch notation to +the corresponding frequency. For example, @code{Asharp_2 + 30 cents} +gets converted to @code{118.578040134 Hz} and @code{55} to +@code{195.99771799 Hz}. + +Since the frequencies of notes are not usually given exactly (and are +typically irrational), the customizable variable +@code{calc-note-threshold} determines how close (in cents) a frequency +needs to be to a note to be recognized as that note +(@pxref{Customizing Calc}). This variable has a default value of +@code{1}. For example, middle @var{C} is approximately +@expr{261.625565302 Hz}; this frequency is often shortened to +@expr{261.625 Hz}. Without @code{calc-note-threshold} (or a value of +@expr{0}), Calc would convert @code{261.625 Hz} to scientific pitch +notation @code{B_3 + 99.9962592773 cents}; with the default value of +@code{1}, Calc converts @code{261.625 Hz} to @code{C_4}. + + + @node Store and Recall, Graphics, Units, Top @chapter Storing and Recalling @@ -35225,6 +35536,28 @@ should also be added to @code{calc-embedded-announce-formula-alist} and @code{calc-embedded-open-close-plain-alist}. @end defvar +@defvar calc-lu-power-reference +@defvarx calc-lu-field-reference +See @ref{Logarithmic Units}.@* +The variables @code{calc-lu-power-reference} and +@code{calc-lu-field-reference} are unit expressions (written as +strings) which Calc will use as reference quantities for logarithmic +units. + +The default value of @code{calc-lu-power-reference} is @code{"mW"} +and the default value of @code{calc-lu-field-reference} is +@code{"20 uPa"}. +@end defvar + +@defvar calc-note-threshold +See @ref{Musical Notes}.@* +The variable @code{calc-note-threshold} is a number (written as a +string) which determines how close (in cents) a frequency needs to be +to a note to be recognized as that note. + +The default value of @code{calc-note-threshold} is 1. +@end defvar + @defvar calc-highlight-selections-with-faces @defvarx calc-selected-face @defvarx calc-nonselected-face @@ -35872,6 +36205,31 @@ keystrokes are not listed in this summary. @r{ v x@: k T @: @: @:utpt@:(x,v)} @r{ v x@: I k T @: @: @:ltpt@:(x,v)} +@c +@r{ a b@: l + @: @: @:lupadd@:(a,b)} +@r{ a b@: H l + @: @: @:lufadd@:(a,b)} +@r{ a b@: l - @: @: @:lupsub@:(a,b)} +@r{ a b@: H l - @: @: @:lufsub@:(a,b)} +@r{ a b@: l * @: @: @:lupmul@:(a,b)} +@r{ a b@: H l * @: @: @:lufmul@:(a,b)} +@r{ a b@: l / @: @: @:lupdiv@:(a,b)} +@r{ a b@: H l / @: @: @:lufdiv@:(a,b)} +@r{ a@: l d @: @: @:dbpower@:(a)} +@r{ a b@: O l d @: @: @:dbpower@:(a,b)} +@r{ a@: H l d @: @: @:dbfield@:(a)} +@r{ a b@: O H l d @: @: @:dbfield@:(a,b)} +@r{ a@: l n @: @: @:nppower@:(a)} +@r{ a b@: O l n @: @: @:nppower@:(a,b)} +@r{ a@: H l n @: @: @:npfield@:(a)} +@r{ a b@: O H l n @: @: @:npfield@:(a,b)} +@r{ a@: l q @: @: @:lupquant@:(a)} +@r{ a b@: O l q @: @: @:lupquant@:(a,b)} +@r{ a@: H l q @: @: @:lufquant@:(a)} +@r{ a b@: O H l q @: @: @:lufquant@:(a,b)} +@r{ a@: l s @: @: @:spn@:(a)} +@r{ a@: l m @: @: @:midi@:(a)} +@r{ a@: l f @: @: @:freq@:(a)} + @c @r{ @: m a @: @: 12,13 @:calc-algebraic-mode@:} @r{ @: m d @: @: @:calc-degrees-mode@:}