# math

math.jal - Collection of mathematical functions.

Author | Rob Hamerling, Michael Watterson Copyright © 2009..2011, all rights reserved.
Adapted-by | Michael Watterson, Eur van Andel, Rob Hamerling
Compiler | 2.4o

Description

    Collection of mathematical routines.

Sources

    Various authors.

Notes

    .
    1. This library contains a number of routines handling 'fixed point' numbers.
       These numbers are contained in a signed word or signed double word
       as  * 256. In other words the digits behind the decimal point are
       stored in the least significant byte of the signed word or signed double word.
       For example a fixed point value '+18.5' is stored in a 16-bits signed word
       with value 256 * 18.5, which is 4736 decimal or 0x1280 hexadecimal.
       You could also think of '+18' (0x12) being stored in the most significant byte
       and '.5' in the least significant byte (0.5 * 256 = 128, or 0x80).
    2. Fixed point math is 8 bits for the decimal part in this library,
       approximately 2 decimal places, the part after the "point" is 0 to 255.
       sword fixed point numbers are thus -127.00 to +127.00 approx.
       When you need bigger numbers replace all swords by sdwords and
       sdwords by sbyte*8, if the compiler can still do the math.

Dependencies

No dependency found

## Summary

### Global variables/contants

- `const byte SINLOOKUP[] = {0, 3, 8, 12, 17, 21, 26, 30, 35, 39, 43, 48, 52, 57,`

### Procedures

- `polar_to_cartesian(sword in radius, sword in angle, sword out xpos, sword out ypos)`

### Functions

- `sqrt32(dword in x) return word`
- `rsin8(sword in radius, sword in angle) return sword`
- `abs16(sword in x) return word`
- `byte_to_fixed(byte in int) return sword`
- `bin2bcd8(byte in bin) return byte`
- `rcos8(sword in radius, sword in angle) return sword`
- `round_fixed(sword in fixed_point) return sbyte`
- `mult_fixed(sword in a, sword in b) return sdword`
- `mod_fixed(sword in a, sword in b) return sword`
- `abs32(sdword in x) return dword`
- `trunc_fixed(sword in fixed_point) return sbyte`
- `sqrt16(word in x) return byte`
- `sign8(sbyte in x) return sbyte`
- `abs8(sbyte in x) return byte`
- `sign16(sword in x) return sbyte`
- `bcd2bin8(byte in bcd) return byte`
- `div_fixed(sword in a, sword in b) return sdword`
- `sign32(sdword in x) return sbyte`
- `digits_word(word in valu) return byte`

## API details

### Global variables/contants

- `const byte SINLOOKUP[] = {0, 3, 8, 12, 17, 21, 26, 30, 35, 39, 43, 48, 52, 57,`

      Title:     Obtain sine value
      Arguments: - radius (signed word)
       angle in degrees (signed word)
      Returns:   signed word
      Original:  Michael Watterson
      Notes:     Sine values scaled to (256 * 1.0 - 1) for values above zero.
      (i.e. add one to lookup if using table directly for other than zeroth Element)
      apart from zero, all values are 1 less than actual
      to allow storage in 1 byte each

### Procedures

- `polar_to_cartesian(sword in radius, sword in angle, sword out xpos, sword out ypos)`

      Title:     Convert polar to cartesian coo-ordinates
      Arguments: - radius (signed word)
       angle in degrees (signed word)
      Returns:   - X-co-ordinate (signed word)
       Y-co-ordinate (signed word)
      Original:  Michael Watterson
      Notes:     Use to rotate angle of a line by calculating endpoints.
      Use to generate quadrature waves by changing angle at a fixed speed.
      If using all 360 degrees in one degree steps, then frequency is step rate / 360

### Functions

- `sqrt32(dword in x) return word`

      Title:     Calculate the square root of an unsigned 32-bits integer
      Arguments: unsigned 32-bits integer
      Returns:   unsigned 16-bits integer
      Original:  Kyle York

- `rsin8(sword in radius, sword in angle) return sword`

      .
      0 to 90 degrees in 1 degree steps
      8-bits resolution sin function R x Sin (angle) in degrees -32767 to +32767
      Result can be same magnitude and opposite sign
      .
      Use to generate audio waves by changing angle at a fixed speed.
      If using all 360 degrees in one degree steps, then frequency is step rate / 360
      At nyquist frequency you only need 0 and 180 degrees, i.e. 1/2 sample rate.
      If sample rate is 48kHz then for 12kHz you have only 4 samples,
      i.e. 90 degree steps at 1.2kHz thus you use 9 degree steps.
      1 degree steps is thus  133.33 Hz if step speed is 48KHz
      PWM can be loaded via this lookup
      Use 128 and add 127 to answer for 8 bit PWM
      Use 512 and add 511 to answer for 10bit PWM
      If summing two frequencies, peak value is twice,
      so add as swords < 16383 and divide sum by 2!
      works with fixed point numbers 256 = 1.0

- `abs16(sword in x) return word`

      Title:     Obtain absolute value of a signed 16-bits integer
      Arguments: signed 16-bits integer
      Returns:   unsigned 16-bits integer
      Original:  Eur van Andel

- `byte_to_fixed(byte in int) return sword`

      Title:     Convert unsigned 8-bits integer to a signed 16-bits fixed point number
      Arguments: unsigned byte
      Returns:   signed 16-bits fixed point number
      Original:  Michael Watterson

- `bin2bcd8(byte in bin) return byte`

      kludgy slow bin2bcd routine
      will convert to 99 for input > 99!
      Original:    Eur van Andel

- `rcos8(sword in radius, sword in angle) return sword`

      Title:     Obtain cosine value
      Arguments: - radius (signed word)
       angle in degrees (signed word)
      Returns:   a signed word
      Original:  Michael Watterson
      Notes:     See with rsin8 function

- `round_fixed(sword in fixed_point) return sbyte`

      Putpose:   Convert signed 16-bits fixed point number to a signed 8-bits integer (rounded)
      Arguments: signed 16-bits fixed point number
      Returns:   signed 8-bits integer
      Original:  Michael Watterson

- `mult_fixed(sword in a, sword in b) return sdword`

      Title:     Multiply 2 signed 16-bits fixed point numbers
      Arguments: 2 signed 16-bits fixed point numbers
      Returns:   signed 32-bits fixed point number
      Original:  Michael Watterson
      Notes:     unlike integer max is 128 * 128  *256 approx

- `mod_fixed(sword in a, sword in b) return sword`

      Title:     Divide 2 signed 16-bits fixed point numbers
      Arguments: 2 signed 16-bits fixed point numbers
      Returns:   signed 16-bits number
      Original:  Michael Watterson
      Notes:     There is probably a better way to do this!

- `abs32(sdword in x) return dword`

      Title:     Obtain absolute value of a signed 32-bits integer
      Arguments: signed 32-bits integer
      Returns:   unsigned 32-bits integer
      Original:  Eur van Andel

- `trunc_fixed(sword in fixed_point) return sbyte`

      Title:     Convert signed 16-bits fixed point number to a signed 8-bits integer (truncated)
      Arguments: signed 16-bits fixed point number
      Returns:   signed byte
      Original:  Michael Watterson

- `sqrt16(word in x) return byte`

      Title:     Calculate the square root of an unsigned 16-bits integer
      Arguments: unsigned 16-bits integer
      Returns:   unsigned 8-bits integer
      Original:  author: Kyle York

- `sign8(sbyte in x) return sbyte`

      Title:     Obtain sign of a signed 8-bits integer
      Arguments: signed 8-bits integer
      Returns:   signed 8-bits integer
      1 : negative
      0 : zero
      +1 : positive
      Original:  Eur van Andel

- `abs8(sbyte in x) return byte`

      Title:     Obtain absolute value of a signed 8-bits integer
      Arguments: signed 8-bits integer
      Returns:   unsigned 8-bits integer
      Original:  Eur van Andel

- `sign16(sword in x) return sbyte`

      Title:     Obtain sign of a signed 16-bits integer
      Arguments: signed 8-bits integer
      Returns:   signed 16-bits integer
      1 : negative
      0 : zero
      +1 : positive
      Original:  Eur van Andel

- `bcd2bin8(byte in bcd) return byte`

      Convert one byte packed bcd to one byte binary.
      input:   byte with bcd data
      output:  none
      returns: byte with binary value of bcd byte
      notes: - A byte in bcd notation contains ((16 * tens) + ones).
      To convert it to a binary value: subtract (6 * tens)
      Algorithm is modeled after an assembler version of
      Scott Dattalo at PicList (but slightly less efficient!).
      Original: Rob Hamerling

- `div_fixed(sword in a, sword in b) return sdword`

      Title:     Divide 2 signed 16-bits fixed point numbers
      Arguments: 2 signed 16-bits fixed point numbers
      Returns:   signed 32-bits fixed point number
      Original:  Michael Watterson

- `sign32(sdword in x) return sbyte`

      Title:     Obtain sign of a signed 32-bits integer
      Arguments: signed 32-bits integer
      Returns:   signed 8-bits integer
      1 : negative
      0 : zero
      +1 : positive
      Original:  Eur van Andel

- `digits_word(word in valu) return byte`

      Title:     Calculate number of significant decimal digits in an unsigned 16-bits integer
      Arguments: unsigned word
      Returns:   unsigned byte
      Original:  Michael Watterson
      Notes:     Uses multiplication by 10 with shifts and addition

## Related samples

Here are the list of samples which use this library:

16f648a | 16f648a_sqrt.jal
16f723 | 16f723_sqrt.jal
16f73 | 16f73_sqrt.jal
16f877 | 16f877_sqrt.jal
16f877a | 16f877a_glcd_ks0108.jal
16f877a | 16f877a_sqrt.jal
16f88 | 16f88_sqrt.jal
16f886 | 16f886_math.jal
18f14k50 | 18f14k50_sqrt.jal
18f2450 | 18f2450_sqrt.jal
18f2520 | 18f2520_sqrt.jal
18f2550 | 18f2550_sqrt.jal
18f2580 | 18f2580_rtc_ds1302_glcd.jal
18f2620 | 18f2620_sqrt.jal
18f2685 | 18f2685_math.jal
18f452 | 18f452_sqrt.jal
18f4550 | 18f4550_sqrt.jal
18f4620 | 18f4620_sqrt.jal
18f6310 | 18f6310_glcd_ks0108.jal
18f6310 | 18f6310_glcd_ks0108_math.jal
18f67j50 | 18f67j50_sqrt.jal