nksp/real_unit_final/01_nksp_real_unit_final.html

<html>
  <head>
    <meta name="author" content="Christian Schoenebeck">
    <title>Real Numbers, Units and Finalness</title>
    <urlpath>Real_Numbers_Units_and_Finalness</urlpath>
    <meta name="description" content="New NKSP Core Language Features: Support for real numbers, standard measuring units and finalness.">
    <link rel="stylesheet" href="http://doc.linuxsampler.org/css/preview.css">
    <script type="text/javascript" src="http://doc.linuxsampler.org/js/preview.js"></script>
  </head>
  <body>
    <p>
      As you might have seen from our change log, I've been recently working on
      a bunch of new core features for our <a href="01_nksp.html">NKSP</a>
      real-time instrument script engine, with the goal to make instrument
      scripting more intuitive and less error prone, especially from a
      musician's point of view.
    </p>
    <p>
      The changes are quite substantial, so here is
      a more detailed description of what's new, how to use those new
      features, what's the motivation behind them, and also a discourse
      about some of the associated language design (and implementation) aspects.
    </p>
    <note class="important">
      Features described in this article refer to LinuxSampler version <b>2.1.1.svn16</b> (or higher).
      So these features are not available in older versions of the sampler.
      And since these are new development features, they still might be subject to change.
    </note>

    <h2 id="64bit">64-Bit Integers</h2>
    <p>
      First of all, integers, i.e. integer number literals (as e.g. <code lang="nksp">4294967295</code>), integer
      variables (like <code lang="nksp">declare $foo := 4294967295</code>), or
      integer array variables (like <code>declare %bar[3] := ( 1, 2, 3 ) </code>),
      and all their arithmetics like
      <code lang="nksp">($foo + 1024) / 24</code> and all built-in functions (as e.g.
      <code>min()</code>), are now all 64 bit with <a href="01_nksp.html">NKSP</a>.<br>
      <br>
      I hear your "<i>Yaaawn</i>" at this point. You might be surprised though about the amount of
      <a href="https://en.wikipedia.org/wiki/Diff">diff</a> involved
      and how often people stumbled over undesired 32-bit truncation with their
      scripts before. So that change alone reduced error-proneness tremendously.
      But let's get on.
    </p>

    <h2 id="real_numbers">Real Numbers</h2>
    <p>
      You are finally no longer limited to integer math with <a href="01_nksp.html">NKSP</a>.
      You can now also use floating point arithmetics which will make calculations,
      that is mathematical formulas in your scripts much easier than before.
      Sounds a bit more interesting, doesn't it?<br>
    </p>

    <h3 id="real_variables">Variables</h3>
    <p>
      We call those floating point numbers
      <i title="One of the most important classes of numbers in mathematics where each <b>real number</b> represents a continous quantity qualified for reflecting a distance on a line, and hence real numbers are commonly used for the numerical value of measurements of physical quantities like e.g. length, temperature, mass, velocity.">
        real numbers
      </i> from now on and you can
      write them like you probably already expected; in simple dotted notation like
      <code>2.98</code>. Likewise there are new variable types for real numbers as well.
      The syntax to declare a real number variable is:
    </p>
    <p>
      <code lang="nksp">
declare ~??real-variable-name?? := ??initial-value??
      </code>
    </p>
    <p>
      Like e.g.:
    </p>
    <p>
      <code lang="nksp">
declare ~foo := 3.14159265
      </code>
    </p>
    <p>
      So it looks pretty much the same as with integer variables, just that you use
      "~" as prefix in front of the variable name instead of "$" that you would
      use for integer variables <b>and</b> the values <b>must always</b> contain a dot so that the parser
      can distinguish them clearly from integer numbers.
      Moreover there is now also a real number array variable type which you can
      declare like this:
    </p>
    <p>
      <code lang="nksp">
declare ???real-array-variable-name??[??amount-of-elements??] := ( ??initial-values?? )
      </code>
    </p>
    <p>
      Like e.g.:
    </p>
    <p>
      <code lang="nksp">
declare ?foo[4] := ( 0.1, 2.0, 46.238, 104.97 )
      </code>
    </p>
    <p>
      Once again, the only differences to integer array variables are that you use
      "?" as prefix in front of the array variable name instead of "%" that you
      would use for integer array variables, <b>and</b> that you <b>must always</b> use a
      dot for each value being assigned.
      And as with integer variables, if you omit to assign initial value(s) for
      your real number variables or real array variables then they are automatically
      initialized with zero value(s) (that is <code>0.0</code> actually).
    </p>
    <note class="remark">
      I actually already had plans for implementing floating point support in
      <i title="NKSP stands for 'is <b>N</b>ot <b>KSP</b>', which denotes its distinction to an existing proprietary language called <i>KSP</i>. NSKP is a script language specifically designed to write real-time capable software extensions to LinuxSampler's sampler engines that can be bundled individually with sounds by sound designers themselves.">NKSP</i>
      much earlier, but I somehow had the feeling that <i>KSP</i> would add it as well.
      And I though before "inventing" again some kind of new syntax set for this feature
      and then having to somehow merge and maintain cross-compatibility between <i>KSP</i> syntax
      and <i>NKSP</i> syntax, I decided to wait a bit, and it
      eventually appeared now on <i>KSP</i> side, so it was a good point to finally fill
      this gap in <i>NKSP</i>.
    </note>

    <h3 id="type_casting">Type Casting</h3>
    <p>
      Like <i>KSP</i> we are (currently) quite strict about your obligation to distinguish
      clearly between integer numbers and real numbers with <i>NKSP</i>. That means blindly
      mixing integers and real numbers e.g. in formulas, will currently cause a parser error
      like in this example:
    </p>
    <p>
      <code>~foo := (~bar + 1.9) / 24  { WRONG! }</code>
    </p>
    <p>
      In this example you would simply use <code>24.0</code> instead of <code>24</code> to
      fix the parser error:
    </p>
    <p>
      <code>~foo := (~bar + 1.9) / 24.0  { correct }</code>
    </p>
    <p>
      That's because, when you are mixing integer numbers and real numbers in mathematical
      operations, like the division in the latter example, what was your intended data type that you
      expected of the result of that division; a real number or an integer result? Because it
      would not only mean a different data type, it might certainly also mean a completely
      different result value accordingly.
    </p>
    <p>
      That does not mean you were not allowed to mix real numbers with integers, it is just
      that you have to make your point clear to the parser what your intention is. For that
      purpose there are now 2 new built-in functions <code>int_to_real()</code> and
      <code>real_to_int()</code> which you may use for required type casts (data type conversions).
      So let's say you have a mathematical formula where you want to mix that formula with
      a real number variable and an integer variable, then you might e.g. type cast the
      integer variable like this:
    </p>
    <p>
      <code>~bla := ~foo / int_to_real($bar)</code>
    </p>
    <p>
      And since this is a very common thing to do, we also have 2 short-hand forms of these
      2 built-in functions in <i>NKSP</i> which are simply <code>real()</code> and <code>int()</code>:
    </p>
    <p>
      <code>~bla := ~foo / real($bar) { same as above, just shorter } </code>
    </p>
    <note>
      The short-hand functions <code>real()</code> and <code>int()</code> only exist in
      <i>NKSP</i>. They don't exist with <i>KSP</i>.
    </note>
    <note class="remark">
      In future we might certainly lift this data type strictness and do it like many other
      programming languages handle this: just showing a parser warning (not an error) on mixed
      integer vs. real number expressions, and at the same time performing always an implied type cast
      of the respective integer to a real number type automatically by the compiler.
    </note>

    <h3>Built-in Functions</h3>
    <p>
      What about real numbers and existing built-in functions? When you check our latest reference
      documentation of <a href="01_nksp_reference.html">NKSP built-in functions</a>,
      you will notice that most of them accept now both, integers and real numbers as arguments
      to their function calls. You should be aware though that the precise acceptance of data
      types and the resulting behaviour change, varies between the individual built-in functions,
      which is due to the difference in purpose of all those numerous built-in functions.
    </p>
    <p>
      For instance the data type of the result returned by <code>min()</code> and <code>max()</code>
      function calls depends now on the data type being passed to those functions. That is
      if you pass real numbers to those 2 functions then you'll get a real number as result;
      if you pass integers instead then you'll get an integer as result instead.
    </p>
    <p>
      Then there are functions, like e.g. the new math functions <code>sin()</code>, <code>cos()</code>,
      <code>tan()</code>, <code>sqrt()</code>, which only accept real numbers as arguments (and
      always return a real number as result). Trying to pass integers will cause a parser error,
      because those particular functions are not really useful on integers at all.
    </p>
    <p>
      Likewise the previously already existing functions <code>fade_in()</code> and <code>fade_out()</code>
      accept now both integers and real numbers for their 2nd argument (<code>??duration-us??</code>),
      but do not allow real numbers for their 1st argument (<code>??note-id??</code>), because for
      a duration real numbers make sense, whereas for a <code>??note-id??</code>
      real numbers would not make any sense and such an attempt is usually a result of some
      programming error, hence you will get a parser error when trying to pass a real number
      to the 1st argument of those 2 built-in functions.
    </p>
    <p>
      There might also be differences how built-in functions handle mixed usage of integers
      and real numbers as arguments, simultaniously for the same function call that is.
      For instance
      the <code>min()</code> and <code>max()</code> functions are very permissive and allow you to mix
      an integer argument with a real number argument. In such mixed cases those 2 functions
      will simply handle the integer argument as if it was a real number and hence the
      result's data type would be a real number. So this would be Ok:
    </p>
    <p>
      <code>
min(0.3, 300)  { OK for this function: mixed real and integer arguments }
      </code>
    </p>
    <p>
      
      Yet other functions,
      like the <code>search()</code>
      function, are very strict regarding data type. So if you are passing an integer array as 1st argument to
      the <code>search()</code> function then it only accepts an integer (scalar) as
      2nd argument, and likewise if you are passing a real number array as 1st argument
      then it only accepts a real number (scalar) as 2nd argument. Attempts passing
      different types, or in a different way to that function, will cause a parser error.
    </p>
    <note>
      Use common sense! The accepted data types of arguments and correspending
      result's data type of built-in functions usually match with your intuition,
      and if it does not for some reason, then
      you always get a clear parser error message immediately when trying to pass a wrong data
      type while typing your scripts (e.g. in Gigedit's script editor). And on doubt you can
      always refer to the <a href="01_nksp_reference.html">reference documentation</a> for
      details of course.
    </note>

    <h3>Comparing for Equalness</h3>
    <p>
      If you are also writing <i>KSP</i> scripts, then you probably already knew most of the things that I
      described above about real numbers. But here comes an important difference that we
      have when dealing with real numbers in <i>NKSP</i>: real number value comparison for equalness and unequalness.
    </p>
    <p>
      In our automated
      <a href="http://svn.linuxsampler.org/cgi-bin/viewvc.cgi/linuxsampler/trunk/src/scriptvm/tests/NKSPCoreLangTest.cpp?view=markup">NKSP core language test cases</a>
      you find an example that looks
      like this (slightly changed here for simplicity):
    </p>
    <p>
      <code>
on init
  declare ~a := 0.165
  declare ~b := 0.185
  declare ~x := 0.1
  declare ~y := 0.25

  if (~a + ~b = ~x + ~y)
    message("Test succeeded")
  else
    message("Test failed")
  end if

end on
      </code>
    </p>
    <p>
      When you add the values of those variables from this example in your head, you will see that the actual
      test in that example theoretically boils down to comparing <code>if (0.35 = 0.35)</code>.
      Hence this test should always succeed. At least
      that's what one would expect if one would do the calculations above manually by humans
      in the real world.
      In practice though, when this script is executed on a computer, the numbers on both sides would
      slightly deviate from <code>0.35</code>. These differences to the expected value are
      actually extremely little, that is very tiny fractions of several digits behind the decimal point,
      but the final consequence would still be nevertheless different values on both sides and this test "would" hence fail.
      These small errors are due to the technical way
      <a href="https://en.wikipedia.org/wiki/Floating-point_arithmetic">floating point numbers are encoded</a>
      on any modern <i>CPU</i> which causes small calculation errors with these summations for instance.
      Due to that very well known circumstance of floating point arithmetics on
      CPUs, it is commonly discouraged with system programming languages like C/C++
      to directly compare floating point numbers for equalness, nor for unequalness for that exact reason.
    </p>
    <p>
      However the use case for the NKSP language is completely different from
      system level programming languages like C/C++. We don't need to be so
      conservative in many aspects those languages need to be. The musical context of
      <i>NKSP</i> simply has different requirements. Simplicity and high level
      handling is more important for <i>NKSP</i> than revealing bit by bit
      of the actual CPU registers bare-bone directly to users of instrument scripts.
      So I decided to implement
      real number equal (<code>=</code> operator) and unequal comparison
      (<code>#</code> operator) to automatically take the expected floating
      point tolerances of the underlying CPU into account.
    </p>
    <p>
      So in short: the
      <u>test case example above does <b>not</b> fail with our <i>NKSP</i> implementation</u>!
    </p>
    <p>
      That does not mean you can simply switch off your head when doing
      real number arithmetics and subsequent comparisons of those calculations.
      Because with every calculation you do, the total amount of calculation
      error (caused by the utilized floating point processing hardware) increases,
      so after a certain amount of subsequent calculations
      our equal/unequal comparisons would fail as well after a certain point.
      But most of the time you will have formulas which end up with a very
      limited amount of floating point calculations before you eventually
      do your comparisons, so in most cases you should just be fine. But keep
      this issue in mind when doing e.g. numeric (large amount of subsequent)
      calculations e.g. in <code>while</code> loops.
    </p>
    <p>
      What about the other comparison operators like <code>&lt;</code>,
      <code>&gt;</code>, <code>&lt;=</code>, <code>&gt;=</code>? Well,
      those other comparison operators all behave like with system level
      programming languages. So these comparison operators currently
      do <b>not</b> take the mentioned floating point tolerances into
      account and hence they behave differently than the <code>=</code>
      and <code>#</code> operators with <i>NKSP</i>.
      The idea was that those other
      comparison operators are typically used for what mathematicians
      call "transitivity". So they are used e.g. for sorting tasks
      where there should always be a clear determinism of the
      comparison results, and where execution speed is an issue as well.
      Because the truth is also that our floating point tolerance
      aware "equal" / "unequal" comparisons come with the price of
      requiring execution of additional calculations on the underlying CPU.
    </p>

    <note class="remark">
      You might wonder now, isn't this still sort of a hack? Wouldn't
      there be a better way to implement real numbers in <i>NKSP</i> so that
      all calculations would behave exactly as we would expect them from
      theoretical math? The short answer is both <b>yes</b> and <b>no</b>.<br>
      <br>
      <b>Yes</b>, we could implement support for real numbers as so called
      <a href="https://en.wikipedia.org/wiki/Computer_algebra_system">algebraic system</a>,
      which would accomplish that real number calculations would always exactly
      result as you would expect them to do from traditional mathematics,
      like certain mathematical software applications use to do it
      (e.g. <a href="https://en.wikipedia.org/wiki/Maple_(software)">Maple</a>).
      However to achieve that we could no longer utilize hardware acceleration
      of the CPU's floating point unit, because it is limited to floating point
      values of fixed precision (e.g. either 32 bit and/or 64 bit).
      Hence we would need to execute a huge amount of instructions on the CPU
      instead for every single real number calculation in scripts, so there would
      be a severe performance penalty.<br>
      <br>
      And <b>no</b>, we actually cannot do that in <i>NKSP</i> at all, because this kind of
      complex real number implementation would require memory allocations at
      runtime, which in turn would violate a key feature of <i>NKSP</i> 
      scripting: its guaranteed real-time stability and runtime determinism.
    </note>

    <h2 id="units">Standard Measuring Units</h2>
    <p>
      If you are coming from <i>KSP</i> then you are eventually going to think next
      "WTF? What is this all about?". But hang with me, no matter how often you
      wrote instrument scripts before, you will most
      certainly regularly come into a situation like described next and we
      have a convenient fix for that.
    <p>

    <h3 id="unit_literals">Unit Literals</h3>
    <p>
      Let's consider you wanted to pause your script at a certain point for let's say
      1 second. Ok, you remember from the back of your head that you need to use the
      built-in <code>wait()</code> function for that, but which value do you need to
      pass exactly to achieve that 1 second break?
      Would it be <code>wait(1000)</code>
      or probably <code>wait(1000000)</code>? Of course now you reach out for the
      reference documentation at this point and eventually find out that it
      would actually be <code>wait(1000000)</code>. Not very intuitive. And
      the large amount of zeros required does not help to make your code necessarily
      more readable either, right?
    </p>
    <p>
      So what about actually writing what we had in mind at first place:
    </p>
    <p>
      <code>
wait(1s)
      </code>
    </p>
    <p>
      It couldn't be much clearer.
    </p>
    <p>
      Or you want a break of 23 milliseconds instead? Then let's just write that!
    </p>
    <p>
      <code>
wait(23ms)
      </code>
    </p>
    <p>
      Now let's consider another example: Say you wanted to reduce volume of some voices by 3.5 decibel.
      You remember that was something like <code>change_vol(??note??, ??volume??)</code>,
      but what would <code>??volume??</code> be exactly? Digging out the docs yet again you
      find out the correct call was <code>change_vol($EVENT_ID, -3500)</code>.<br>
      <br>
      We can do better than that:
    </p>
    <p>
      <code>
change_vol($EVENT_ID, -3.5dB)
      </code>
    </p>
    <p>
      You rather want a slight volume increase by just 56 milli dB instead?
    </p>
    <p>
      <code>
change_vol($EVENT_ID, +56mdB)
      </code>
    </p>
    <p>
      Or let's lower the tuning of a note by -24 Cents:
    </p>
    <p>
      <code>
change_tune($EVENT_ID, -24c)
      </code>
    </p>
    <p>
      I'm sure you got the point. We are naturally using standard measuring
      units in our daily life without noticing their importance, but they actually help us a
      lot to give some otherwise purely abstract numbers an intuitive meaning to us.
      Hence it just made sense to add measuring units as core feature of the NKSP
      language, their built-in functions, variables and whatever you do with them.
    </p>

    <h3>Calculating with Units</h3>
    <p>
      Having said that, these examples above were just meant as warm up appetizer.
      Of course you can do much more with this feature than just passing them
      literally to some built-in function call as we did above so far.
      You can assign them to variables, too, like:
    </p>
    <p>
      <code>
declare ~pitchLfoFrequency := 1.2kHz
      </code>
    </p>
    <p>
      You can use them in combinations with integers or real numbers, and of course
      you can do all mathematical calculations and comparisons that you would
      naturally be able to do in real life. For instance the following example
    </p>
      <code>
on init
  declare $a := 1s
  declare $b := 12ms
  declare $result := $a - $b
  message("Result of calculation is " &amp; $result)
end on
      </code>
    </p>
    <p>
      would print the text <code>"Result of calculation is 988ms"</code> to the terminal
      (notice that <code>$a</code> and <code>$b</code> actually used different units here).<br>
      <br>
      Or the following example
    </p>
      <code>
on init
  declare ~a := 2.0mdB
  declare ~b := 3.2mdB
  message( 4.0 * ( ~a + ~b ) / 2.0 + 0.1mdB )
end on
      </code>
    </p>
    <p>
      would print the text <code>"10.5mdB"</code> to the terminal.<br>
      <br>
      Or let's make this little value comparison check:
    </p>
    <p>
      <code>
on init
  declare ~foo := 999ms
  declare ~bar := 1s
  if (~foo &lt; ~bar)
    message("Test succeeded")
  else
    message("Test failed")
  end fi
end on
      </code>
    </p>
    <p>
      which will succeed of course
      (notice again that <code>~foo</code> and <code>~bar</code> used different units here as well).<br>
      <br>
      So as you can see the units are not just eye candy for your code, they
      are actually interpreted actively by the script engine appropriately such that all your
      calculations, comparisons and function calls behave as
      you would expect them to do from your real-life experience.
    </p>

    <h3>Unit Components</h3>
    <p>
      In the examples above you might have noticed that the units' components
      were shown in different colors. That's not a glitch of the website,
      that's intentional and in fact NKSP code on this website is in general,
      automatically displayed in the same way as with e.g. Gigedit's instrument
      script editor. So what's the deal?
    </p>
    <p>
      If you take the value <code>6.8mdB</code> as an example, you have in front
      the <code>??numeric component?? = 6.8</code> of course, followed
      by the <code>??metric prefix?? = <span class="up">md</span></code> for
      "milli deci" (which is always simply some kind of multiplication factor)
      and finally the fundamental <code>??unit type?? = <span class="ut">B</span></code> for "Bel" (which actually gives the number its final meaning).
    </p>
    <p>
      So here's where language design comes into play. From language point of view both
      the <code>??numeric component??</code> and the optional <code>??metric prefix??</code>
      are runtime features which may change at any time,
      whereas the optional <code>??unit type??</code> is always
      a constant, "sticky", parse-time feature that you may never change at runtime.
      That means if you define a variable like e.g. <code>declare $foo := 1s</code>
      that variable <code>$foo</code> is now firmly tied to the unit type "seconds" for your entire script.
      You may change the variable's numeric component and metric prefix later on at any time like e.g.
      <code>$foo := 8ms</code>, but you must not change the variable ever to a different
      unit type later on like <code>$foo := 8Hz</code>. Trying to switch
      the variable to a different unit type that way will cause a parser error.
      Changing the fundamental unit type of a variable is not allowed, because it
      would change the semantical meaning of the variable.
    </p>
    <note class="remark">
      What may look like a lousy limitation of the technical implementation
      is in fact an intentional language design decision and is actually a feature,
      called <i>determinism</i>.
      The price of this limitation of forcing unit types to be a constant parse time
      feature of variables and expressions comes with the profit of buying substantial
      error checks at parse time, and that in turn helps you to write more
      reliable instrument scripts in a shorter amount of time. For instance no
      matter how complex your mathematical formulas are in your scripts, the parser
      will always be able to check already at parse-time whether the
      final, evaluated results of your formulas and overall code that you pass to
      built-in functions, will finally be of correct unit type expected by the
      respective function that you are going to call with them as function arguments.
      Or in other words: the parser is able to check the correct meaning of your formulas at parse-time.
      So the parser will stop you immediately
      from doing such and similar mistakes by raising a parser error immediately while you are typing
      your script code. So you neither
      have to load the script into the sampler, nor do you have to run and test the
      code just to spot such kind of mistakes. You will always see them instantly
      in the code editor while you are typing your code.
    </note>
    <p>
      So getting back and proceed with an early example, this code would be fine:
    </p>
    <p>
      <code>
on note
  declare ~reduction := -3.5dB  { correct unit type }
  change_vol($EVENT_ID, ~reduction)
end note
      </code>
    </p>
    <p>
      That's Ok because the built-in function <code>change_vol()</code>
      optionally accepts the unit <code>B</code> for its 2nd argument.
      Whereas the following would immediately raise a parser error:
    </p>
    <p>
      <code>
on note
  declare ~reduction := -3.5kHz  { WRONG unit type for change_vol() call! }
  change_vol($EVENT_ID, ~reduction)
end note
      </code>
    </p>
    <p>
      That's because using the unit type Hertz for changing volume with the
      built-in function <code>change_vol()</code> does not make any sense,
      that built-in function expects a unit type suitable for volume changes,
      not a unit type for frequencies, and hence it is clearly a
      programming mistake. So getting this error in
      practice, you may have simply picked a wrong variable by accident for
      a certain function call for instance and the parser will immediately
      point you on that undesired circumstance.
    </p>
    <p>
      As another example, you may now also use units with the built-in random number
      generating function like e.g. <code>random(100Hz, 5kHz)</code>. The function
      would then return an arbitrary value between <code>100Hz</code> and <code>5kHz</code>
      each time you call it that way, so that makes sense. But trying e.g. <code>random(100Hz, 5s)</code>
      would not make any sense and consequently you would immediately get a parser
      error that you are attempting to pass two different unit types to the <code>random()</code> function,
      which is not accepted by this particular built-in function.
      And these kinds of parse-time errors are always detected,
      no matter whether you are literally passing constant
      values like in the simple example here, but also through every other means like
      variables and complex mathematical expressions.
    </p>
    <p>
      The following tables list the unit types and metric prefixes currently supported by <i>NKSP</i>.
    </p>
    <p>
      <table>
        <tr>
          <th>Unit Type</th>  <th>Description</th>  <th>Purpose</th>
        </tr>
        <tr>
          <td><code>s</code></td>
          <td>short for "seconds"</td>
          <td>May be used for time durations.</td>
        </tr>
        <tr>
          <td><code>Hz</code></td>
          <td>short for "Hertz"</td>
          <td>May be used for frequencies.</td>
        </tr>
        <tr>
          <td><code>B</code></td>
          <td>short for "Bel"</td>
          <td>May be used for volume changes and other kinds of relative changes
              (e.g. depth of envelope generators).</td>
        </tr>
      </table>

      <table>
        <tr>
          <th>Metric Prefix</th>  <th>Description</th>  <th>Equivalent Factor</th>
        </tr>
        <tr>
          <td><code>u</code></td>
          <td>short for "micro"</td>
          <td>10<sup>-6</sup>&nbsp;&nbsp;=&nbsp;&nbsp;0.000001</td>
        </tr>
        <tr>
          <td><code>m</code></td>
          <td>short for "milli"</td>
          <td>10<sup>-3</sup>&nbsp;&nbsp;=&nbsp;&nbsp;0.001</td>
        </tr>
        <tr>
          <td><code>c</code></td>
          <td>short for "centi"</td>
          <td>10<sup>-2</sup>&nbsp;&nbsp;=&nbsp;&nbsp;0.01</td>
        </tr>
        <tr>
          <td><code>d</code></td>
          <td>short for "deci"</td>
          <td>10<sup>-1</sup>&nbsp;&nbsp;=&nbsp;&nbsp;0.1</td>
        </tr>
        <tr>
          <td><code>da</code></td>
          <td>short for "deca"</td>
          <td>10<sup>1</sup>&nbsp;&nbsp;=&nbsp;&nbsp;10</td>
        </tr>
        <tr>
          <td><code>h</code></td>
          <td>short for "hecto"</td>
          <td>10<sup>2</sup>&nbsp;&nbsp;=&nbsp;&nbsp;100</td>
        </tr>
        <tr>
          <td><code>k</code></td>
          <td>short for "kilo"</td>
          <td>10<sup>3</sup>&nbsp;&nbsp;=&nbsp;&nbsp;1000</td>
        </tr>
      </table>
    </p>
    <p>
      Of course there are much more standard unit types and metric prefixes than
      those, but currently we only support those listed above. Simply because
      I found these listed ones to be actually useful for instrument scripts.
    </p>
    <note class="important">
      When changing tuning, which is commonly expected by musicians in "Cents",
      like e.g.: <code>change_tune($EVENT_ID, -24c)</code>, you might have noticed
      already from the markup color here, that this is actually not handled as a unit
      type by the <i>NKSP</i> language and that's why it is not listed as
      a unit type in the table above. So tuning changes in "Cents" is actually just a value
      with metric prefix "centi" and without any unit type, since tuning changes
      in "Cents" is really just a relative multiplication factor for changing the pitch of
      a note depending on the current base frequency of the note.<br>
      <br>
      This might look a bit odd to you, it is semantically however absolutely correct
      to handle tuning changes in "Cents" that way by the language. You can still also use expressions like
      "milli Cents", e.g.: <code>change_tune($EVENT_ID, +324mc)</code>, which is also
      valid since we (currently) allow a combination of up to 2 metric prefixes with <i>NKSP</i>.<br>
      <br>
      The obvious advantage of not making "Cents" a dedicated unit type is that we can
      just use the character "c" in scripts both for tuning changes, as well as for conventional
      "centi" metric usage like <code>1cs</code> ("one centi second").
      The downside of this design decision (that is "Cents" being defined as metric prefix) on the other hand
      means that we loose the previously described parse-time stickyness feature that we
      would have with "real" unit types, and hence also loose some of the described
      error detection mechanisms that we have with "real" unit types at parse time.<br>
      <br>
      <u>In practice that means:</u> you need to be a bit more cautious when doing calculations
      with tuning values in "Cents" compared to other tasks like volume changes, because with every
      calculation you do in your scripts, you might accidentally drop the "Cents" from your unit, which
      eventually will cause e.g. the <code>change_tune()</code> function to
      behave completely differently (since a value without any metric prefix
      will then be interpreted by <code>change_tune()</code> to be a value in "milli cents",
      exactly like this function did before introduction of units feature in <i>NKSP</i>).
    </note>

    <h3 id="unit_conversion">Unit Conversion</h3>
    <p>
      Even though you are not allowed to change the unit type of a variable itself
      by assignment at runtime, that does not mean there was no way to get rid of
      units or that you were unable to convert values from one unit type to a
      different unit type. You can do that very easily actually with <i>NKSP</i>,
      exactly as you learned in school; i.e. by multiplications and divisions.
    </p>
    <p>
      Let's say you have a variable <code>$someFrequency</code> that you
      use for controlling some LFO's frequency by script, and for some reason you really
      want to use the same value of that variable (for what reason ever)
      to change some volume with <code>change_vol()</code>, then all you have
      to do is dividing the existing unit type away, and multiplying it
      with the new unit type:
    </p>
    <p>
      <code>
on note
  declare $someFrequency := 100Hz
  change_vol($EVENT_ID, $someFrequency / 1Hz * 1mdB)
end note
      </code>
    </p>
    <p>
      Which would convert the variable's original value <code>100Hz</code>
      to <code>100mdB</code> before passing it to the <code>change_vol()</code>
      function. So this actually did 3 things:
    </p>
    <p>
      <ol>
        <li>the divsion (by <code>/ 1Hz</code>) dropped the old unit type (Hertz),</li>
        <li>the multiplication (by <code>* 1mdB</code>) added the new unit type (Bel)</li>
        <li>and that multiplication also changed the metric prefix (to milli deci) before the result is finally passed to the <code>change_vol()</code> function.</li>
      </ol>
    </p>
    <p>
      And since <code>change_vol()</code> would now receive the value
      in correct unit type, this overall solution is hence legal and accepted by the parser without any complaint.
      And this type of unit conversion does not break any parse-time determinism
      and error detection features either, since it is not touching the variable's
      unit type directly (only the temporary value eventually being passed to the <code>change_vol()</code> function here),
      and so the result of the unit conversion expressions above
      can always reliably be evaluated by the parser at parse-time.
    </p>
    <note class="important">
      There are some intended limitations when performing unit type conversions though.
      For instance you are never allowed to multiply some unit type with another unit type
      in <i>NKSP</i>, neither different unit types like e.g. <code>100Hz * 1B</code>, nor
      with the same unit type like e.g. <code>4s * 8s</code>. That's because we don't have
      any practical usage for e.g. "square seconds" or other kinds of mixed unit types
      in instrument scripts.
      So trying to create a number or variable with more than one unit type will always
      raise a parser error. So keep that in mind and use common sense when writing
      calculations with units. And like always: the parser will always point you on
      misusage immediately.
    </note>

    <h3>Array Variables</h3>
    <p>
      And as we are at limitations regarding units:
      Currently <b>unit types</b> are not accepted for array variables yet. <b>Metric prefixes</b>
      are allowed though!
    </p>
    <p>
      <code>
declare %foo[4] := ( 800, 1m, 14c, 43)   { OK - metric prefixes, but no unit types }
declare %bar[4] := ( 800s, 1ms, 14kHz, 43mdB)   { WRONG - unit types not allowed for arrays yet }
      </code>
    </p>
    <p>
      Main reason for that current limitation is that unlike with scalar variables,
      accessing array variables at runtime with an index by yet another (runtime changeable)
      variable might break the previously described parse-time determinism of unit types.
      That means if we just take the array variable <code>%bar[]</code> declared above
      and would access it in our scripts with another variable like:
    </p>
    <p>
      <code>
%bar[$someVar]
      </code>
    </p>
    <p>
      then what would that unit type of that array access be? Notice that the array variable
      <code>%bar[]</code> was initialized with 3 different unit types for its individual elements.
      So the unit type of the array access would obviously depend on the precise
      value of variable <code>$someVar</code>, which most probably will change at runtime and
      hence the compiler would not know at parse-time yet.
    </p>
    <note class="remark">
      This limitation will most probably be lifted later on by allowing exactly one unit type
      for an array variable, so that the array would be initialized with exactly the same unit
      type for all its elements to retain the parse-time determinism that we were talking about.
    </note>

    <h2 id="finalness">Finalness</h2>
    <p>
      Here comes another new core language feature of <i>NKSP</i> that you certainly don't
      know from <i>KSP</i> (as it does not exist there), and which definitely requires an
      elaborate explanation of what it is about: "finalizing" some value.
    </p>

    <h3>Default Relativity</h3>
    <p>
      When changing synthesis parameters, these are commonly <i>relative</i> changes, depending
      on other modulation sources. For instance let's say you are using <code>change_vol()</code>
      in your script to change the volume of voices of a note, then the actual, final volume
      value being applied to the voices is not just the value that you passed to <code>change_vol()</code>,
      but rather a combination of that value and values of other modulation sources of volume
      like a constant gain setting stored with the instrument patch, as well as a continuously
      changing value coming from an amplitude LFO
      that you might be using in your instrument patch, and you might most certainly also use
      an amplitude envelope generator which will also have its impact on the final volume of course.
      All these individual volume values are multiplied with each other in real-time by the sampler's engine core
      to eventually calculate the actual, final volume to be applied to the voices, like illustrated in the following
      schematic figure.
    </p>
    <img src="nksp_multi_mods_rel.png" caption="Relative Modulation (Default Behaviour)">
    <p>
      This <i>relative</i> handling of synthesis parameters is a good thing, because multiple
      modulation sources combined make up a vivid sound. However there are situations where this
      combined behaviour for synthesis parameters is not what you want. Sometimes you want to be
      able to just say in your script e.g. "Make the volume of those voices exactly -6dB. Period. I mean it!".
      And that's exactly what the newly introduced "final" operator <code>!</code> does.
    </p>

    <h3>Final Operator</h3>
    <p>
      <code>
on note
  declare $volume := -6dB
  change_vol($EVENT_ID, !$volume)  { '!' makes value read from variable $volume to become 'final' }
end note
      </code>
    </p>
    <p>
      By prepending an exclamation mark <code>!</code> in front of an expression as shown in the code above,
      you mark that value of that expression to be "final",
      wich means the value will bypass the values of all other modulation sources, so the
      sampler will ignore all other modulation sources that may exist, and
      will simply use your script's value exclusively for that synthesis parameter,
      as illustrated in the following figure:
    </p>
    <img src="nksp_multi_mods_fin.png" caption="Force 'Finalness' by Script">
    <p>
      You can of course revert back at any time to let the sampler process that synthesis parameter
      relatively again by calling <code>change_vol()</code> and just passing
      a value for volume without "finalness" (i.e. without <code>!</code> operator) this time.
    </p>
    <p>
      In the previous code example, the "finalness" was applied to the temporary value
      being passed to the <code>change_vol()</code> function, it did not change
      the information stored in variable <code>$volume</code> at all though. So this is different
      from:
    </p>
    <p>
      <code>
on note
  declare $volume := !-6dB   { store 'finalness' directly to variable $volume }
  change_vol($EVENT_ID, $volume)
end note
      </code>
    </p>
    <p>
      In the latter code example the actual "finalness" is stored directly now
      to the <code>$volume</code> variable instead. Both approaches
      make sense depending on the actual use case. For instance if you only
      need "finalness" in rare situations, then you might use the prior
      solution by using the "final" operator just with the respective function call,
      whereas in use cases where you would always apply the
      <code>$volume</code> "finally" and probably need to pass it to several
      <code>change_vol()</code> function calls at several places in your script,
      then you might store the "finalness" information directly to the variable instead.
    </p>
    <note class="remark">
      <i>KSP</i> is also using the exclamation mark in front of variable names of string arrays.
      Our usage of the exclamation mark character for this "finalness" feature
      does not cause a language conflict with
      that aspect though, because variable names (i.e. containing exclamation mark) are
      resolved by the language before our unary <code>!</code> "final" operator is resolved in
      expressions.
    </note>

    <h3>Mixed Finalness</h3>
    <p>
      Like with the other new language features described previously above, we also
      have some potential ambiguities that we need to deal with when applying "finalness".
      For instance consider this code:
    </p>
    <p>
      <code>
on note
  declare $volume := !-6dB   { store 'finalness' directly to variable $volume }
  change_vol($EVENT_ID, $volume + 2dB)  { raises parser warning here ! }
end note
      </code>
    </p>
    <p>
      Should the resulting, expected volume change of <code>-4dB</code> be applied as
      "final" value or as <i>relative</i> value instead?
      Because the problem here is that <code>!-6dB</code> obviously means "final",
      whereas </code>+ 2dB</code> is actually a <i>relative</i> value to be added.
    </p>
    <p>
      In the current version of the sampler the value to be applied in this case would be "final", so you will not get a parser error,
      however you will get a parser warning to make you aware about this ambiguity.
      So to fix the example above, that is to to get rid of that parser warning, you can simply add an exclamation
      mark in front of the other number as well like:
    </p>
    <p>
      <code>
on note
  declare $volume := !-6dB   { store 'finalness' directly to variable $volume }
  change_vol($EVENT_ID, $volume + !2dB)  { '!' fixes parser warning }
end note
      </code>
    </p>
    <p>
      Also built-in functions will behave similarly as described above. Certain built-in functions
      accept <i>finalness</i> for all of their arguments, some functions accept <i>finalness</i> for only certain
      arguments and some functions won't accept <i>finalness</i> at all. Like with the other new core language
      features always use common sense and quickly think about whether it would make sense if a
      certain function would accept <i>finalness</i> for its argument(s). Most of the time your guess will be
      right, and if not, then the parser will tell you immediately with either an error or warning, and the
      <a href="01_nksp_reference.html">NKSP built-in functions reference</a> will help you out with
      details in such rare cases where things might not be clear to you immediately.
    </p>

    <h3>Implied Finalness</h3>
    <p>
      Here comes the point where the feature circle of this article closes: the unit type "Bel" used
      in the examples for the "final" operator above is somewhat special, since the unit type "Bel" is
      in general used for <i>relative</i> quantities like i.e. volume changes. Tuning changes (i.e. in "Cents") are
      also relative quantities.
    </p>
    <p>
      However other unit types like "seconds" or "Hertz" are <i>absolute</i>
      quantities. That means if you are using unit types "Hertz" or "seconds" in your scripts, then their
      values are automatically applied as <i>implied</i> "final" values, as if you were using the <code>!</code>
      operator for them in your code. The parser will raise a parser warning though to point you on that
      circumstance.
    </p>
    <p>
      The following table outlines this issue for the currently supported unit types.
    </p>
    <p>
      <table>
        <tr>
          <th>Unit&nbsp;Type</th>  <th>Relative</th>  <th>Final</th>  <th>Reason</th> 
        </tr>
        <tr>
          <td>None</td>
          <td>Yes, by default.</td>
          <td>Yes, if <code>!</code> is used.</td>
          <td>If no unit type is used (which includes if <b>only</b> a metric prefix is used like e.g. <code>change_tune($EVENT_ID, -23c)</code>) then such values can be used both for relative, as well as for 'final' changes.</td>
        </tr>
        <tr>
          <td><code>s</code></td>
          <td>No, never.</td>
          <td>Yes, always.</td>
          <td>This unit type is naturally for absolute values only, which implies its value to be always 'final'.</td>
        </tr>
        <tr>
          <td><code>Hz</code></td>
          <td>No, never.</td>
          <td>Yes, always.</td>
          <td>This unit type is naturally for absolute values only, which implies its value to be always 'final'.</td>
        </tr>
        <tr>
          <td><code>B</code></td>
          <td>Yes, by default.</td>
          <td>Yes, if <code>!</code> is used.</td>
          <td>This unit type is naturally for relative changes. So this unit type can be used both for relative, as well as for 'final' changes.</td>
        </tr>
      </table>
    </p>
    <note class="remark">
      Since unit types like <i>seconds</i> and <i>Hertz</i> are naturally always used for absolute values
      in real life,
      it might be considerable to drop the mentioned parser warnings which currently occur
      if those units are used in scripts without having used the <code>!</code> operator.
    </note>

    <h3>Array Variables</h3>
    <p>
      As with unit types, the same current restriction applies to "finalness" in conjunction with
      array variables at the moment: you may currently <b>not</b> apply "finalness" to the elements of array variables yet.
    </p>
    <p>
      <code>
declare %foo[3] := ( !-6dB, -8dB, !2dB )  { WRONG - finalness not allowed for arrays (yet) ! }
      </code>
    </p>
    <p>
      The reason is also exactly the same, because <i>finalness</i> is a parse-time required information
      and an array access by using yet another variable like e.g. <code>%foo[$someVar]</code> might
      break that parse-time awareness of "finalness" for the compiler.
    </p>
    <note class="remark">
      Likewise we might certainly lift that restriction later on by
      allowing <i>finalness</i> to be applied to arrays by initializing <b>all</b> members of an array to be all "final".
    </note>

    <h2>Backward Compatibility</h2>
    <p>
      You might be asking, what do all those new features mean to your existing instrument scripts,
      do they break your old scripts?
    </p>
    <p>
      The clear and short answer is:&nbsp;&nbsp;&nbsp;<b>No</b>, of course <u>they do <b>not</b> break your existing scripts</u>!
    </p>
    <p>
      Our goal was always to preserve constant behaviour for existing sounds,
      so that even ancient sound files in GigaSampler v1 format still would sound
      exactly as you heard them originally for the 1st time many, many years ago
      (probably with GigaSampler at that time).
      And that means the same policy applies to instrument scripts as well of course.
    </p>
    <p>
      You can also arbitrarily mix your existing instrument scripts by just partly using the new
      features described in this article at some sections of your scripts, while 
      at the same time preserving your old code at other code sections. So these features
      are designed that they won't break anything existing, and that they always
      collaborate correctly in an arbitrary, mixed way with old <i>NKSP</i> code.
    </p>

    <h2>Status Quo</h2>
    <p>
      That's it!&nbsp;&nbsp;For now ...
    </p>
    <p>
      This is the current development state regarding these new <a href="01_nksp.html">NKSP</a>
      core language features. It might not be the final word though. I am aware certain
      aspects that I decided can be argued about (or maybe even entire features).
      And that's actually one of the reasons why I decided to write this (even for my habits)
      quite long and detailed article, which also explained the reasons for individual language design
      decisions that I took.
    </p>
    <p>
      You can however share your thoughts and arguments about these new features with us
      on the <a href="https://sourceforge.net/projects/linuxsampler/lists/linuxsampler-devel">mailing list</a>
      of course!
    </p>
    <note class="important">
      Keep in mind, the earlier you come up with suggestions for changes, the higher the chance
      that it might actually become changed and vice versa!&nbsp;&nbsp;&nbsp;(See "Backward Compatibility" above)
    </note>
  </body>
</html> 