Mathematical Operations
The symbols used in most computer programming languages for performing basic mathematical operations work as you’d expect in Csound.
To begin with, the equals sign (=) is used as the assignment operator. Whatever variable appears on the left side of the equals sign is assigned the result of the arithmetic operation on the right side. Programmers refer to the variable on the left side of the equals sign as an l-value (“l” being an abbreviation for “left”). The l-value must be a variable; it can’t be a constant or an expression. This is legal:
kampsum = kenv1 + kenv2
But this isn’t:
5 = kenv1 + kenv2
And this isn’t either:
kenv1 + kenv2 = 5
These statements would be meaningless, because no computer programming language would know what you meant to do with them. This may look more sensible:
5 = kenv1
But it’s also defective and won’t compile. The way to assign a value of 5 to the variable kenv1 is to make the variable the l-value:
kenv1 = 5
On the right side of the equals sign we can put whatever formula we need, using the standard set of symbols: +, -, *, /, ^, and %. Some of these may be less familiar to you than others, so let’s look at them all.
Most of these symbols are used to perform an operation on two values. For instance, the plus symbol (+) is used for addition. You probably knew that already. We might write:
iresult = ivalA + ivalB
This tells Csound to take whatever number is currently stored in ivalA, add it to the number stored in ivalB, and put the result in the variable named iresult. Variables are basically just named storage locations in computer memory. Csound will keep track of the actual storage location; you will always refer to it by name. (Csound has no equivalent of the pointer data type used in general-purpose programming languages such as C to refer to memory locations.)
The minus symbol (-) is a little different, however. It has two uses: It can subtract one value from another, or it can be used to negate a value. That is, it’s shorthand for multiplying the value by − 1. If ivalA is 6, then -ivalA is −6—and conversely: If ivalA is −6, then -ivalA is 6.
Multiplication is performed using the asterisk (*):
iresult = ivalA * ivalB
Division uses the slash symbol (/):
kresult = kvalA / kvalB
Division has to be used with care, however. As you may have learned in algebra class, it’s not possible to divide by zero. In the statement above, if the value of kvalB is ever zero, there may be a run-time error, causing Csound to crash. (The crash may not be immediate. The result of the operation will be stored as NaN—not a number. If this result is then fed into an opcode that chokes on it, a crash is the likely result.) Since signals in Csound are normally in the form of floating-point numbers, an actual value of zero is not too likely. To be safe, though, you would be well advised to use a workaround—the divz opcode. This divides two numbers, but if the divisor is ever zero it outputs a substitute value instead. Details can be found in the manual.
The modulus operator (%) performs a division and outputs the remainder. For example:
ivalA = 7 ivalB = 3 ivalC = ivalA % ivalB
Here, ivalC will be 1. When we perform the division, 3 goes into 7 twice (3 * 2 = 6), and the remainder after the division is 7 – 6, or 1.
The caret symbol (^) is the power-of operator. For example:
ival = 2^8
Here, ival is 2 to the 8th power, which is 256.
Note Unlike some computer programming languages, Csound does not include the += and -= operators. This is illegal:
ival += 1
In other languages, this statement would add 1 to whatever value was stored in ival. In Csound, the addition must be performed explicitly:
ival = ival + 1
Nor does Csound have any pre/post-increment/decrement operators, so this type of thing is not possible:
kdata table kindex++, giDataTable
Using Parentheses
When computer programmers talk about precedence, they’re referring to the fact that when a complex mathematical formula is written into code, some operations are performed before others. Generally (and this is true in Csound, though not in all programming languages), multiplication and division are performed before addition and subtraction. For example, if you write:
iresult = 7 – 3 * 2
the value of iresult will be 1, not 8. The multiplication (3 * 2) will be performed first, and then the subtraction (7 – 6). If you want the other result, the way to do it is by grouping the terms in the statement with parentheses:
iresult = (7 – 3) * 2
The operations inside of parentheses will always be performed before operations outside of them. Parentheses can be nested, if desired:
iresult = ((7 – 3) * 2) / 9
If you aren’t sure whether parentheses are needed in a statement in order to get the result that you want, it’s always okay to add them as a safety precaution. This can also make the code easier to read. These two statements are exactly equivalent:
iresult = (ival1 * ival2) – (ival3 * ival4) + (ival5 / ival6) iresult = ival1 * ival2 – ival3 * ival4 + ival5 / ival6
But the first one is easier to read and is less likely to contain an inadvertent error.
If two operators have equal precedence (as is the case with + and -, and with * and /), Csound will perform the operations in left-to-right order.
I was unable to find any information in The Canonical Csound Reference Manual about the precedence of the % and ^ operators. In my tests, it appears that % has the same precedence as * and /, while ^ has a higher precedence than any of the others. Raising a number to a power, in other words, always happens before other operations are performed. The manual does warn, however, that ^ should be used “with caution as precedence may not work correctly.” A safer approach is to use the pow opcode. Also worth note: In the formula (a ^ b), b cannot be an audio-rate variable. This is because the value in an audio-rate variable is not a single number; it’s a vector of numbers. However, pow can be used safely with audio-rate variables:
Acubed pow asig, 3
Care must be taken, however. If the value of the audio signal ever rises past 1.0, taking the signal to a higher power can increase the output level rather drastically. On the other hand, pow with an odd integer for the exponent is a quick way of adding a few overtones to a sine wave. An even number will rectify the wave (no peak will drop below 0) and transpose it up by an octave. Non-integer exponents and negative exponents should be avoided with pow.
Other Useful Mathematical Operations
Csound provides a good basic suite of other mathematical operations. These are generally in the form of opcodes rather than operators. The “Mathematical Functions” and “Trigonometric Functions” pages in the manual (which appear under the header “Mathematical Operations” in the left-side index) give lists. For more complex mathematical processes, you may want to resort to incorporating Python code in your Csound instrument. (For more on using Python, see Chapter 10, “Using Csound with MIDI, OSC, Pd, Python, and Live Audio.”)
Also on the “Mathematical Functions” page is powershape. This opcode is more useful for DSP than for math: It continuously raises an audio signal to an arbitrary power. powershape is probably best used when 0dbfs=1.0, because raising signals greater than 1.0 to a power greater than 1 can easily result in astronomical audio levels.
Here are the most useful math functions:
abs Returns the absolute value of a number. (If the number is negative, abs makes it positive.) Useful for transforming negative p3 values, among other purposes.
ceil Returns the smallest integer not less than x. (Compare to floor.)
cos, cosh, cosinv Cosine functions.
exp Returns e to the power of x. (The example in the manual is fun to play with.)
floor Returns the greatest integer not greater than x.
frac Returns the portion of a decimal number to the right of the decimal point. For instance, frac(2.3) = 0.3.
int The opposite of frac. Returns the integer portion of a number. frac(2.3) = 2.0.
log, log10, logbtwo For calculating natural, base 10, and base 2 logarithms.
max Returns the greatest of two or more values.
maxabs Takes the absolute values of two or more inputs and returns the largest. (The output is always non-negative.)
min Returns the smallest of two or more values.
minabs Takes the absolute values of two more inputs and returns the smallest. (The output is always non-negative.)
pow Returns the value of one number to the power of another number. (Similar to the ^ operator, but may be safer.)
round Returns the integer value nearest to x. (As the manual notes, if the fractional part of x is exactly 0.5, the behavior of round is undefined. This probably means it could return either the higher integer or the lower one.)
sin, sinh, sininv Sine functions.
sqrt Returns the square root of x.
tan, tanh, taninv, taninv2 Tangent functions.