Mathematics utilities Isis software documentation

# Mathematics utilities

This documents explains the various mathematics utilities available in Isis, including bitwise operators, interpolation routines, and the random number generator.

### Numerical constants

pi # 3.1415926535897932385 These constants are pre-defined in Isis.

### Basic operators

(+ arg arg ...) # add arguments (- arg arg ...) # subtract arguments in order (* arg arg ...) # multiply arguments (/ arg arg ...) # divide arguments in order (% arg arg ...) # modulo arguments in order (add arg arg ...) # same functionality as above (sub arg arg ...) (mul arg arg ...) (div arg arg ...) (mod arg arg ...) (abs arg) # absolute value These primitives apply mathematical operations to any number of arguments, in order from left to right, except for abs which accepts only one argument. You can use either the symbolic or spelled-out versions of the function names.

All of these operators will accept integers, real numbers, or lists of these types. Characters and addresses are also acceptable, but only in addition or subtraction. All other types are illegal and will generate an error message. The result will be the same type as the first argument, and all of the arguments are cast to the type of the first argument before the calculation is performed.

-> (- 69 42) 27 -> (+ [3 4 5] [54 -25 11]) [ 57 -21 16 ] -> (+ 'a' 25) 'z' -> (+ 1 2.9 3.9) 6 -> (- 0xf 1) 0xe

### Exponents and logarithms

(pow base exp) # raise base to exp power (log10 x) # log base 10 (exp x) # exponential function (e^x) (log x) # log base e (sqrt x) # square root These operators accept integer or real number arguments, but the result will always be a real number.
-> (pow 2 8) 256.0 -> (sqrt 16) 4.0 -> (log10 1385.455731) 3.141592653

### Trigonometric operators

(sin radians) # sine (cos radians) # cosine (tan radians) # tangent (asin x) # arcsine (acos x) # arccosine (atan x) # arctangent [-pi/2, pi/2] (atan2 y x) # arctangent [-pi, pi] (sinh radians) # hyperbolic sine (cosh radians) # hyperbolic cosine (tanh radians) # hyperbolic tangent (degrad degrees) # convert degrees to radians (raddeg radians) # convert radians to degrees These trigonometric will accept integer or real number arguments, but the result will always be a real number.
-> (cos (degrad 30)) 0.866025 -> (sin (degrad 30)) 0.500000 -> (raddeg (atan2 (/ (sqrt 2) 2) (/ (sqrt 2) 2))) 45.000000

### Other operators

(min val val ...) # return minimum of all arguments (max val val ...) # return maximum of all arguments (clamp min max num) # clamp number to a range (ceil num) # ceiling function (floor num) # floor function min and max return the minimum and maximum of the two or more arguments passed to them. If not all the arguments are numbers, the result is undefined.
-> (min 5 7 3 4 9) 3 -> (max pi (sqrt 6) 3) 3.141592654
clamp forces a value inside of a certain range. You pass the minimum, the maximum, and the value you want to clamp. If the value is less than the minimum, the minimum is returned. If the value is greater than the maximum, the maximum is returned. Otherwise, the original value is returned. The type of the return will be the same as the type of the value being clamped.
-> (clamp 0 255 -5) 0 -> (clamp 0 255 259) 255 -> (clamp 0 255 42) 42 -> (clamp 0 255 85.4) 85.400000 -> (clamp 0 255 342.3) 255.000000
ceil and floor return the nearest integral value greater or less than the given number. The result will be a real number.
-> (ceil 42.2) 43.0 -> (floor 42.2) 42.0

### Random numbers

(seed-random num) # seed the random number generator (random) # generate random number between 0 and rand-max (random max) # random number between 0 and max (inclusive) (random min max) # random number between min and max (inclusive) rand-max # default maximum random number These primitives control the random number generator. The pre-defined variable rand-max is the highest random number that will ever be generated. Call seed-random with any number you like. Then call random with no arguments to get a random integer between 0 and rand-max. Call it with one number to get a random integer between 0 and that number (inclusive). Call it with 2 numbers to get an integer between those two numbers (inclusive).
-> rand-max 32767 -> (seed-random 42) 42 -> (random) 19081 -> (random 10) 5 -> (random 42 69) 55
Often the random number generator is seeded with the current system time, which can be obtained via the get-time primitive from the time utilities library.
-> (seed-random ((get-time) 0)) 1001286456 -> (random 0 100) 28 -> (seed-random ((get-time) 0)) 1001286465 -> (random 0 100) 49

### Interpolation

(linear-interpolate frac val1 val2) # linear interpolate between val1 and val2 (cubic-interpolate frac val1 val2 val3 val4) # cubic interpolate between val2 and val3 These functions perform interpolation on integers, real numbers, or lists of these types. The first argument of each should be a real number between 0.0 and 1.0 specifying the interpolation point. linear-interpolate takes 2 more arguments (the values to be interpolated). cubic-interpolate takes 4 more arguments (the interpolation will occur between the two middle values, with the outer values used as outer control points). The type of the result will be the same as val1 for linear interpolation, and val2 for cubic.
-> (linear-interpolate .4 0.0 10.0) 4.000000 -> (cubic-interpolate .4 4.0 0.0 10.0 7.0) 3.616000 -> (cubic-interpolate .4 100.0 0.0 10.0 -300.0) 11.440000

### Bitwise operators

(bit-and val val ...) # bitwise and (bit-or val val ...) # bitwise or (bit-xor val val ...) # bitwise exclusive or (bit-left val shift) # bitwise left shift (bit-right val shift) # bitwise right shift (bit-not val) # bitwise not (& val val ...) # same as bit-and (| val val ...) # same as bit-or (^ val val ...) # same as bit-xor (<< val shift) # same as bit-left (>> val shift) # same as bit-right (~ val) # same as bit-not These are the bitwise and, or, exclusive or, left shift, right shift, and not operators, respectively. They work on integers only. The and, or, and xor operations will accept multiple arguments. The symbolic and spelled-out function names are equivalent.
-> (<< 2 4) 32 -> (bit-left 2 4) 32 -> (bit-and 15 24) 8 -> (bit-or 15 24) 31 -> (bit-xor 15 24) 23 -> (| 1 4 16 128) 149