reference documentation error for mc wrapper "exponential" message

Hi.

I'm trying to teach mc to various groups of students, and I'm noticing some problems with the documentation of the exponential message.

The documentation page "Generating Message to the MC Wrapper" says :

[...] The first argument is the value of the exponent in the series and the second argument is the base that is raised to the exponent. [...]

I'm looking at the numbers that are generated and trying to calculate them myself, and what's actual happening is not what's stated.

For the message "exponential [val1] [val2]"

[val1] is the negative of the step value used as the increasing exponent for the natural exponential base over the number of channels, starting at 0.

The base is e (2.71828), so for a 4 channel object, if val1 is 1, the exponent will start at 0 and then increase by -1 until 4 values are generated. This will be e^0, e^-1, e^-2, e^-3

This value is then multiplied by val2, which is the scale value, and not the "base that is raised to the exponent".

So for "exponential 1 10", the series is

[10*e^0] [10*e^-1] [10*e^-2] [10*e^-3] or

[10] [3.679] [1.353] [0.498]

In another example, "exponential -2 20"

the result is

[20*e^0] [20*e^2] [20*e^4] [20*e^6] or

[20] [147.781] [1091.963] [8068.576]

I'm not sure why the exponent was multiplied by -1 in this implementation. I guess it was so that in the normal use case of scaling amplitudes down over channels, you wouldn't have to use a negative, but I think this is a false simplification, and it also makes the understanding of the arguments more complicated. As for the rest of the explanation in the ref page, I can imagine that since the reality is a bit complicated and difficult to explain, the simpler explanation was used, but if there's a place for the detailed information, it should be the reference pages...

--

Here's an idea for the reference text. Not perfect and still sounds a bit complicated, but more correct than the existing text.

To generate an exponentially increasing or decreasing series of values applied to all instances in the wrapper, use the exponential or scaledexponential messages. The first argument is the negative of the step value used as the increasing exponent for the natural exponential base over the number of channels, starting at 0. The second argument is the scaling value to be applied to the natural exponential result.

So for "exponential 1 10", the series is decreasing :

[10*e^0] [10*e^-1] [10*e^-2] [10*e^-3] OR [10] [3.679] [1.353] [0.498]

For "exponential -2 20", the series is increasing and the exponent steps by 2 each time:

[20*e^0] [20*e^2] [20*e^4] [20*e^6] OR [20] [147.781] [1091.963] [8068.576]

A simpler explanation would be that the first argument is the step value for the exponent in the series and the second argument is the scaling value. Negative exponents cause values to increase over the series while positive exponents cause values to approach zero. The scaledexponential variant divides values in the series by the number of instances in the wrapper, resulting in an overall range that is independent of the number of instances.

Here's a patch that demonstrates.

Thanks in advance.

Tom

----------begin_max5_patcher----------

1566.3oc4Y88qZaCE9Yt+UXg5CaUbihyu.pzj5dYOtIs02J2UYBFvsA6HaG3

1V0829N1NABk.j6Hgoo8.PhSh+Nemy24jiMe8gACmKdlpFhdC58nAC95CCFX

GxLvfxyGLbC44zLhxdaCSEa1P45gibWSSeVaG+ODnkBIZ1P5y4BNbGLRFBiv

9yFNBoWSQJpjQUHlBsflJoDEiuB8lY72i8eM8O8eBgbG8H9vgAGNL7Izu86l

SLCE5kLdp8ZdgwglC78hlN4oY7Y7e4Dq3w.TPClAiu2LH7E1KV8THkllqPy+

LJ.QIoqQZ1FpwVC1aq1iB1eTz9iRbFZfiQQi8FOojQSwdSSrV6D+jIdwiSdp

xMlw3zTQA25KiKGLWRUfwPzLA+CMdGFuepHSHcQPrm+Hj+9ufSQOUdmrE1nj

X9GeLJoBUdwFFOipsQV7gAEE5pQ8qrEhNcM3p9fjlpcnEDXAIL17yTeK3iiL

XZdju8vCluFcixpeFoXaxynRSrIivsNCzNQQ1BzbJDzHZajaISpzHhbUgYZL

gWavFBinsjrBpUbdTHlwqqGpT.JvICGdxDkRxLBE6b4g9U5JvP1dX1TnTRgh

5tN7HhJ0EEI1Rk0QZ2ZVFEkKTrqLCj7bovH99BUJ7PuqzLnKpqs2RjLBXmKX

aYKfmq7wOlbfN1bFDYmC1hXIbYklvSObi6j.ZT4HDH4JxzFpBWgvsVOIKCII

7UktaapyBZNE9BPFltyL4dMptCup5N7lT2Qco5N.Otl5FRl6V086DnUTN3g0

TiytVfM6y0qOAZ2ZEMKipfqtLZCwtLFcgUz.wpyGcMBr5IAFEDL2mJq1PUJx

JHDZkcMmbwqRBJU.0R1.bfbH2sUiF6y8pRFgz4BPdcj8L+njlCxpz0DNmloF

A.QjVIJHF8KSLZQZqw8.kLp4rNmI3RB92Q9F1kx2IAcg5sTLbh58j2wN7p9l

fFXbPiLNnQFW4GbCo+bN0Q2gC26LavYDMw4.BRrddm6v3g5T2ghpQuBi7QuZ

OipQyvI8OMmZeEbnsjEzfwsPRNcGX0mvwLlRurvjG1.ECdIMVbVJZfnMzz29

SbxMQyOxzdozrr4YhzOUY8KEb8RRJ8nTL.elBzylAmTNnTr6Ht.Y61yiZv2D

ewvuARE6KVHwljV2vaUoRQVVcC4XuXzAj2wVnWastpac8oOsAGNYC00aEz5v

93XywgQfjq5ykhI3nDW8FaPIr7km9cq360nGwdMo6h5hTqkYBxkEdisbLw0R

PHtOxuzn4nFSsdIuVH3bTbNzD2UCktXWruq6dWVVeTFwakTTj2DW8eAgyyx0

qxSWYjD2qFhG2GzrfmSR+joGE+lzs3ocQP0oaG0FALF6hsI6Wq1Mv44EZMTN

rAZM4hzJmHgBPZp7CTNYdF87E2vWTG2BMbYNZT02cawnFqEgStm0hhmZ6kLN

tWTuegghP9MQx3W.ICuV0npeYbcaBpkh2v9o7aSEewQcQeMWjag9g06PsWJ5

Bka0GszulnZ3co1qKTF4p.cq8ieF5BKrF8VfsvhGKzXzOgxE69A5rYiXb7O9

ZFO3ezpUhuqsZDYUE3IQ8xBV99cpsA8PbR+upkw1pWgSrh9oi6cpFbFph6cp

FFXU5gwg2IpBQ0FXZje+yTW8rvpsOq2Y5iMS0v39mpgQ00uQ+2X8ngI+eX8n

imzmqGcSpmhs5uPu0r0jJTTS5uwcQqCaLaIe09exVwAuTKR9J2HHrey6DjcF

r6s428++YmQy3G6QThBYZkEU9pPzg8vbAUoYt+dlZ2iYsbny4zaKPlcH7pHY

ZR6lQxrIcWmSwc.RUNlKiTRWfTRKPph32FRQs.otv4gaCkB5BAgYeWf2hdEo

2ztfSgsgSgcEmtZ5TWHHLqS7pduNoDgMDfagzC2E.cUmWRWfjwbCZCR2ryqM

U8vcRhaapP7cYBB4Bp8uPC2+PadccSP6eSPGmb2d+U78BIypktOHE4e27dia

iD4zLNWmTj77sTYUK4VPftH+n6u+01g9PnCP2oI1Skzs6ag2162PhD5kSCMx

UHcsD+bhqqxgaDfTjWvJSD.5APZ6P0z9rJub4A1FYe3aO72.UW2Ck

-----------end_max5_patcher-----------