NAPA Library - Jul 20 2025

DOCUMENTATION ON THE HEADERS
OF THE GENERIC NAPA LIBRARY

\Simulate\NapaDos\Hdr

NAPA generic files

Documentation in 'napa.hdr'

     ** GENERIC HEADER FOR NAPA SIMULATION - 4.40 COMPATIBLE - *******************************************************************

     This header 'napa.hdr' or the header 'napatool.hdr' -MUST- be called as first header of each NAPA simulation netlist '.nap'.
     It is possible to extend or modify this file. Backup this file before any change !

     See also file 'napatool.hdr'.

     This header provides the definition of 2 -REQUIRED- functions of the NAPA simulator:
       void napa_init(void);
       void napa_close(void);

     They are currently providing information on the simulation and may be tuned to match the actual computing environment
     or the team's or the user's wishes.

     This header is compatible with current NAPA generic header libraries and provides utilities expected by the functions located
     in these header files.

     Use 'directive REPEAT <some_integer_number>' to set the number of repetitions of tasks made by tools like FFT, TF, ..
     (e.g  RMS average of FFT's...)

     Use 'directive LOGFILE <"filename">' to create a log file used by some user functions especially in debug mode.
     Corresponding file pointer is <FILE* stdlog>. If filename is not provided, a file named "<sourcefilename>.log" is created.

     Use 'directive NO_STOPWATCH'   to deactivate time statistics       on 'stderr'.
     Use 'directive NO_STATUS'      to deactivate simulation statistics on 'stderr'.
     Use 'directive NO_TITLE'       to deactivate the title             on 'stderr'.

     Directive 'GNUPLOT_CALL'   activates (YES) /deactivates (NO) the call of the software Gnuplot at the end of the simulation.
     Directive 'debug SAMPLING' triggers output of information about sampling frequencies in all segments of the netlist.

     A few NAPA functions and NAPA macros, made available by this header file:

       Macro    'HELP(x)'        [to help debug, this macro is activated if directive 'debug help' is present in the NAPA netlist]

       Function 'eng(x, n)'      [to format number as a string]

       Function 'number3(n)'     [to format number as a string, grouping digits by 3 separated by a blank for better readability]

       Function 'time2ASCII(t)'

       Function 'f1flush(fptr, ...)'
       Function 'f2flush(fptr1, fptr2, ...)'
       Function 'f1printf(fptr, ...)'
       Function 'f2printf(fptr1, fptr2, ...)'

       Function 'compact_string(str)'
       Function 'extract_line(str1, str2)'
       Function 'join_2_strings(str1, str2)'
       Function 'join_3_strings(str1, str2, str3)'
       Function 'replace_string(str, origin, rep)'
       Macro function 'STRINGIFY(x)'
       Macro function 'BEGINOFSTRING(str)'
       Macro function 'ENDOFSTRING(str)'
       Macro function 'ISEMPTY(str)'
       Macro function 'ISNOTEMPTY(str)'

       Function 'simplify_pathname(str)'
       Function 'shorten_pathname(str, n)'

Documentation in 'toolbox.hdr'

     YOUR NAPA TOOLBOX INDEX

     Pathnames of tools and user defined functions are placed here.
     File pathname is referred to directory containing this file 'toolbox.hdr'.

     USAGE:    header <toolbox.hdr>

       Call the resources of any of these functions in the NAPA netlist at the condition
       that they are referenced in one of the files included below.

     See also file 'napatool.hdr'.

     All functions are referenced here at the exception of functions defined in directory 'Resource',
     which are considered to be used directly by user functions and tools and not directly
     from a NAPA netlist ('.nap', '.net' or '.dat' files).

Documentation in 'napatool.hdr'

     ** GENERIC HEADER FOR NAPA SIMULATION ***************************************************************************************

     This header is placed as first header resource of each NAPA simulation netlist.

     USAGE:    header <napatool.hdr>

     It is replacing advantageously the 2 lines:

               header <napa.hdr>
               header <toolbox.hdr>

NAPA registered C functions

Documentation in '..\Function\array.hdr'

     NAPA initialization functions:

     "randomize_array", "stuck_array"

     Initialization of a digital array file.

     USAGE: init void randomize_array(<size>, <mini>, <maxi>, <"file.ram">)
              Data initialized randomly with values in the interval [mini, maxi].

     USAGE: init void stuck_array(<size>, <value>, <"file.ram">)
              All data initialized to <value>.

Documentation in '..\Function\AWG.hdr'

      American Wire Gauge related functions.

      Wire Gauges 36 ... 0      (larger gauges are not supported)

        AWG_d(g)    Diameter of wire of gauge 'g'                                        (m)
        AWG_s(g)    Cross sectional area of wire of gauge 'g'                            (m^2)
        AWG_n(g)    Number of turns of a wire of gauge 'g' to build a coil of 1 meter    (turns/m)

Documentation in '..\Function\A_law.hdr'

      A-Law Companding Functions.

      y = compress_A_law(x)            -1.0 <= x <= 1.0
      x =   expand_A_law(y)            -1.0 <= y <= 1.0

      A_CONSTANT       87.6                                             European Standards

Documentation in '..\Function\bessel_i.hdr'

     'bessel_i(o,x)'  Modified Bessel functions of the first kind, where 'o' is the order of the function (positive integer)

Documentation in '..\Function\bessel_j.hdr'

     'bessel_j(o,x)'  Bessel functions of the first kind, where 'o' is the order of the function (positive integer)

Documentation in '..\Function\bessel_k.hdr'

     'bessel_k(o,x)'  Modified Bessel functions of the second kind, where 'o' is the order of the function (positive integer)

Documentation in '..\Function\bessel_y.hdr'

     'bessel_y(o,x)'  Bessel functions of the second kind, where 'o' is the order of the function (positive integer)

Documentation in '..\Function\choice.hdr'

      Macro functions selecting an input between m proposed inputs

       l = choice_between_i(m, i0, ...)      returns a  I_TYPE,  ie. a long long integer
       d = choice_between_d(m, d0, ...)      returns a  R_TYPE,  ie. a double float
      *s = choice_between_s(m, s0, ...)      returns a  C_TYPE*, ie. a pointer to char

      The number of arguments <i0>..., <d0>... or <s0>... is variable

      ****** CAUTION ******: There is NO automatic cast of arguments! Be careful to check input types and CAST constants !!!!!

      EXAMPLE in a NAPA netlist:

          ivar  mychoice   1

          dvar  mic_in   ...
          dvar  aux_in   ...
          dvar  test     ...
          ivar  sig      ...

          declare (true)  (mychoice >= 0) && (mychoice < 3)                // a good idea to test the value of 'mychoice' at init

          ivar in1  choice_between_i(mychoice,    0LL, 1024LL, sig )       // constants must be written as long long constants !!!
          dvar in2  choice_between_d(mychoice, mic_in, aux_in, test)
                                          |        ^       ^      ^
                                          |        |       |      |
                                          |        |       |      |
                                          |        #0      #1     #2
                                          |                ^
                                          |________________|

          'in1' gets the value 1024LL,      the input #1 in the list of the 3 long long integer numbers.
          'in2' gets the value of 'aux_in', the input #1 in the list of the 3 double float numbers.

Documentation in '..\Function\cmp3.hdr'

     Function 'cmp3(x,y)',  the three-valued compare function

     This function returns   -1LL    if x <  y
                              0LL    if x == y     (if absolute difference is smaller than EPSILON)
                             -1LL    if x >  y

Documentation in '..\Function\coherent.hdr'

     COHERENT SAMPLING.

     Coherent sampling is an important concept in signal processing. It allows to obtain better results from FFT based tools by
     removing the windowing functions and their side effects. User proposes a frequency target, function returns the closest
     coherent signal frequency. It is important to note that the coherent frequency does depend on the local sampling frequency
     (FSL) and to the number of sampled data.

     NAPA mathematical functions:  'coherent()'
                                   'coherent_linsweep()',  'coherent_logsweep()',
                                   'coherent_lindomain()', 'coherent_logdomain()'

     USAGE:  coherent(target, numsim)
               Returns the coherent test frequency around the frequency 'target'.
               'num_sim' is the number of samples used by the analysis tool.

     USAGE:  coherent_linsweep(control, fmin, fmax, num, numsim)
               Returns a frequency between 'fmin' and 'fmax' depending on 'control' and 'num' value, coherent with the local
               sampling frequency for an analysis using 'numsim' samples of data points. Progression as linear as possible.

     USAGE:  coherent_logsweep(control, fmin, fmax, num, numsim)
               Returns a frequency between 'fmin' and 'fmax' depending on 'control' and 'num' value, coherent with the local
               sampling frequency for an analysis using 'numsim' samples of data points. Progression as logarithmic as possible.

     USAGE:  coherent_lindomain(control, fmin, fmax, numsim)
               Returns a frequency between 'fmin' and 'fmax' depending on 'control' value, coherent with the local sampling
               frequency for an analysis using 'numsim' samples of data points. Repartition as linear as possible.

     USAGE:  coherent_logdomain(control, fmin, fmax, numsim)
               Returns a frequency between 'fmin' and 'fmax' depending on 'control' value, coherent with the local sampling
               frequency for an analysis using 'numsim' samples of data points. Repartition as logarithmic as possible.

     CAUTION:   THESE FUNCTIONS USE LOCAL SAMPLING FREQUENCY FSL,  PLACE THEM IN THE RIGHT NAPA SEGMENT!

     Example:
      ..
      fs    512000.0
      ivar  NUMPTS  250000
      dvar  target  1000.0
      ..
      interpolate 2
      ..
      dvar   freq    coherent(target, NUMPTS)                        //  FSL: 1024.0 kHz
      update freq
      node   out     sin  0.0  1.0  freq  0.0
      node   void    itool fft "stdout"  out 1.0  NUMPTS             //  FSL: 1024.0 kHz
      ..
      directive  WINDOW     NONE
      debug      COHERENT
      ..

     The frequency determined by the function 'coherent' will depend on the local sampling frequency (1024 kHz) and the number of
     points (250000). The coherent frequency is valid for the tool 'fft' as it is working at the same sampling frequency and is
     collecting the same number of data (250000).

     The directive 'debug COHERENT' triggers the output of a debug information table:

            NAPA Debug Information: (     coherent)
             Sampling frequency : 1.024e+006 Hz
             Number of samples  : 250000
             Frequency target   : 1000 Hz
             Coherent frequency : 995.328 Hz
             Frequency deviation: -4.672 Hz
             Oversampling ratio : 1028.81
             Number of periods  : 243

     The frequency computed by the function (995.328 Hz) corresponds to an integer number of sinewave periods (here 243) and is
     the nearest coherent frequency to the target.This sinewave is therefore coherently sampled for the FFT process which does not
     need any windowing.

     It is important to double check that the coherent frequency is defined in a segment running at the same sampling frequency
     that the analysis tool (fft, ...) and that the number of sampling points is identical!

Documentation in '..\Function\constant.hdr'

     A few Physical Constants      - 2014 CODATA Recommended Values -

        K()                    Boltzmann Constant                  J.K-1
        H()                    Planck Constant                     J.s

        EPSILON0()             Permittivity of Vacuum              F.m-1
        MU0()                  Permeability of Vacuum              H.m-1
        C0()                   Speed of Light in Vacuum            m.s-1
        Z0()                   Characteristic Impedance of Vacuum  Ohm
        Q()                    Elementary Charge                   C
        EV()                   Electron Volt                       J
        ME()                   Mass of Electron                    kg

        G()                    Gravitational Constant              m3.kg-1.s-2

     see file "./_function.lib".

Documentation in '..\Function\control.hdr'

     Functions 'linsweep()', 'logsweep()', lindomain()', 'logdomain()'

     These C functions can be called by "algebra", "ialgebra" or "dalgebra" nodes, to define variables "dvar" or "ivar", or
     anywhere a C function is allowed.

     These functions have their equivalent macro defined in the code produced by the NAPA compiler.
     These functions here offer an extra check thanks to ANSI-C prototyping.

     Be careful to choose an interval not including 0.0 for logsweep() and logdomain().

     USAGE:      LINSWEEP(c,b,e,n)
             or  linsweep(c,b,e,n)      'n' steps from 'b' to 'e' controlled by 'c'

                 LOGSWEEP(c,b,e,n)
             or  logsweep(c,b,e,n)      'n' steps from 'b' to 'e' controlled by 'c'

                 LINDOMAIN(c,b,e)
             or  lindomain(c,b,e)       between 'b' to 'e' controlled by 'c'

                 LOGDOMAIN(c,b,e)
             or  logdomain(c,b,e)       between 'b' to 'e' controlled by 'c'

     See files "domain.hdr" and "sweep.hdr" for similar functions synchronized to analysis tools.

Documentation in '..\Function\convert0.hdr'

     Functions 'd2i()', 'i2d()'

     These functions have their equivalent macro defined in the code produced by
     the NAPA compiler. They offer an extra check thanks to ANSI-C prototyping.

     USAGE:   d2i(x)  or  D2I(x)    converts   x   in a long long integer (with rounding)
              i2d(n)  or  I2D(n)    converts   n   in a double float

     The functions are equivalent to the macros. They offer an extra check thanks to ANSI-C prototyping.
     Macros are defined in the C code built by the NAPA compiler.

Documentation in '..\Function\convert1.hdr'

     Functions 'lin2db()', 'db2lin()', 'pow2db()', 'db2pow()'.

     These functions have their equivalent macro defined in the code produced by the NAPA compiler.
     They offer an extra check thanks to ANSI-C prototyping.

     USAGE:   LIN2DB(x,r)  or  lin2db(x,r)    converts   x   in  (20.0 * LOG10(x/r) )
              DB2LIN(x,r)  or  db2lin(x,r)    converts   x   in  (   r * 10^(x/20.0))

              POW2DB(x,r)  or  pow2db(x,r)    converts   x   in  (10.0 * LOG10(x/r) )
              DB2POW(x,r)  or  db2pow(x,r)    converts   x   in  (   r * 10^(x/10.0))

Documentation in '..\Function\convert2.hdr'

     Functions 'deg2rad()', 'rad2deg()'.

     These functions have their equivalent macro defined in the code produced by the NAPA compiler.
     They offer an extra check thanks to ANSI-C prototyping.

     USAGE:   DEG2RAD(x)   or  deg2rad(x)     converts   from degree  to radian
              RAD2DEG(x)   or  rad2deg(x)     converts   from radian  to degree

     In addition, radians_to_degrees(), degrees_to_radians() makes the conversion

     See also the functions in "..\Resources\trig.hdr"

Documentation in '..\Function\convert3.hdr'

     Macros                           'C2K()', 'K2C()', 'C2F()', 'F2C()',
     and the corresponding functions  'c2k()', 'k2c()', 'c2f()', 'f2c()'.

     USAGE:    C2K(t)  or  c2k(t)    converts from degree Celsius    to Kelvin
               K2C(t)  or  k2c(t)    converts from Kelvin            to degree Celsius

               C2F(t)  or  c2f(t)    converts from degree Celsius    to degree Fahrenheit
               F2C(t)  or  f2c(t)    converts from degree Fahrenheit to degree Celsius

Documentation in '..\Function\convert4.hdr'

     Functions 'p2t()', 't2p()'

     USAGE:     p2t(n)  converts   'n' sampling periods in time period.
                t2p(t)  converts   time period 't' in a number of sampling periods.

     EXAMPLE:
                header <napa.hdr>
                header <toolbox.hdr>
                ...
                fs    2.5e4                 // sampling frequency is 25000.0 Hz.
                ...
                decimate 25                 // local sampling frequency FSL is 1000.0 Hz.
                ...
                dvar  t01   p2t(100)        //      t01   is 0.1 second.
                dvar  p100  t2p(0.1)        //      p100 is 100 local sampling periods.
                ...

     Be careful on rounding errors (kind of synchronization errors) for t2p().

Documentation in '..\Function\convert5.hdr'

     Functions 'np2db()', 'db2np()'

     USAGE:     np2db(x)  converts   neper to decibel.
                db2np(x)  converts   decibel to neper.

Documentation in '..\Function\dec2bin.hdr'

      dec2bin(n)   converts a decimal form into a binary form (for output)

      USAGE:  dec2bin(n) where n is a long integer in interval [0, 1024[

      LIMITATION!  This is an output FORM in decimal, not in a binary CODE.
                   This is why, it is impossible to process numbers larger than 1024,
                   as their code is longer than the largest decimal number represented by a long integer 2147483647L

      Example:   n =   0     ->            0
                       1     ->            1
                       2     ->           10
                       3     ->           11
                       4     ->          100
                       5     ->          101
                       .     ->          ...
                       7     ->          111
                       8     ->         1000
                       9     ->         1001

                    ....          ..........
                    1023     ->   1111111111
      TOO BIG >>>   1024     ->  10000000000   > longer than largest integer [2147483647]

Documentation in '..\Function\diode.hdr'

     Semiconductor diode with internal resistance, Shockley model

     diode_Iv(V, Rs, Is, n)     LARGE signal current in a diode,    function of voltage
     diode_Rv(V, Rs, Is, n)     LARGE signal resistance of a diode, function of voltage

     diode_Vi(I, Rs, Is, n)     LARGE signal voltage in a diode,    function of current
     diode_Ri(I, Rs, Is, n)     LARGE signal resistance of a diode, function of current

                                       with 3 parameters:   Is is the saturation current
                      I                                     n  is the diode ideality factor
                     -->                                    Rs is the internal resistance
                V  ------+
                         |                          Note:   for silicon diode   n = 1..2
                       __|__
                       \   /
         D(Is, Rs, n)   \ /
                       __V__
                         |
                        _|_

Documentation in '..\Function\dirac.hdr'

     Functions   'dirac (<m>)'
                 'dirac2(<m>, <n>)'

         where <m>, <n> are numbers of local sampling periods.

      dirac(m)
        |
        |                                 AREA = FSL * 1.0/FSL = 1.0
     . .|. FSL . . . . __ . . .
        |              ||
        |              ||
        |              ||
        |            ->||<- 1.0/FSL
        |              ||
        |              ||
        |______________||___________________________________
                                                         time
                      m/FSL

      dirac2(m, n)
        |
        |
     . .|. FSL . . . . __ . . . . . __ . . . . . __ . . .
        |              ||           ||           ||
        |              ||           ||           ||
        |    1.0/FSL ->||<-         ||           ||
        |              ||           ||           ||
        |              ||           |<---n/FSL-->||
        |              ||           ||           ||
        |______________||___________||___________||_________
                                                         time
                      m/FSL       (m+n)/FSL    (m+2n)/FSL...

      Note:  Do not use in non linear environment

      Tips:  Use function t2p(t) to convert time in number of local sampling periods, but be careful about synchronization errors.

             NB: function t2p() in file "../Function/convert4.hdr"

Documentation in '..\Function\ET12.hdr'

      Function   ET12()          Music - '12-TET',  Twelve-Tone Equal Temperament, A4 @ 440Hz

      USAGE:    <freq> = ET12(<note>, <octave>)

                with  <freq>   output frequency in Hz
                      <note>   in [0..12[  see table below.
                      <octave> in [0..32[

        0  ........  A  ...........   ET12_A                           ...............   [ La        ]
        1  ........  A#, Bb  ......   ET12_Asharp   ==   ET12_Bflat    ...............   [ La#, Sib  ]
        2  ........  B  ...........   ET12_B                           ...............   [ Si        ]
        3  ........  C  ...........   ET12_C                           ...............   [ Do        ]
        4  ........  C#, Db  ......   ET12_Csharp   ==   ET12_Dflat    ...............   [ Do#, Reb  ]
        5  ........  D  ...........   ET12_D                           ...............   [ Re        ]
        6  ........  D#, Eb  ......   ET12_Dsharp   ==   ET12_Eflat    ...............   [ Re#, Mib  ]
        7  ........  E  ...........   ET12_E                           ...............   [ Mi        ]
        8  ........  F  ...........   ET12_F                           ...............   [ Fa        ]
        9  ........  F#, Db  ......   ET12_Fsharp   ==   ET12_Gflat    ...............   [ Fa#, Solb ]
       10  ........  G  ...........   ET12_G                           ...............   [ Sol       ]
       11  ........  G#, Ab  ......   ET12_Gsharp   ==   ET12_Aflat    ...............   [ So#, Lab  ]

                   note---+    +---octave
                          |    |
      EXAMPLES:   ET12(ET12_A, 0)         returns    27.500 Hz
                  ET12(ET12_A, 1)         returns    55.000 Hz
                  ET12(ET12_A, 2)         returns   110.000 Hz
                  ET12(ET12_A, 3)         returns   220.000 Hz
                  ET12(ET12_A, 4)         returns   440.000 Hz    <<  A4 @ 440Hz                   ( following norm ISO16 )
                  ET12(ET12_A, 5)         returns   880.000 Hz
                  ET12(ET12_A, 6)         returns  1760.000 Hz
                  ...

                  the "five-tone" motif of 'Close Encounters of the Third Kind':
                  ET12(ET12_Asharp, 2)    returns   116.541 Hz
                  ET12(ET12_C,      3)    returns   261.626 Hz
                  ET12(ET12_Gsharp, 2)    returns   207.652 Hz
                  ET12(ET12_Gsharp, 1)    returns   103.826 Hz
                  ET12(ET12_Dsharp, 2)    returns   155.563 Hz

      NB:  Other temperaments for the twelve-note chromatic scale (not implemented)
           - Just intonation
           - Pythagorean tuning
           - Meantone temperament
           - Lucy's tuning
           - Well temperament
           - Tempered timbres
           - ...

     logarithms of A4 and A5 frequencies.

     12 equally spaced notes per octave. We then apply arc-logarithms to those points and arrive the equal-tempered tuning.

     Frequency calculation for Equal-Tempered tuning   < A4 = 440Hz >

      #      Notes               Octave=1   Octave=2   Octave=3   Octave=4   Octave=5   Octave=6  ...      Notes
      -      ---------------     --------   --------   --------   --------   --------   --------           ---------------------
      0  ==  A                     55.000    110.000    220.000  < 440.000 >  880.000   1760.000           La
      1  ==  Asharp == Bflat       58.270    116.541    233.082    466.164    932.328   1864.655           La diese  == Si bemol
      2  ==  B                     61.735    123.471    246.942    493.883    987.767   1975.533           Si
      3  ==  C                     65.406    130.813    261.626    523.251   1046.502   2093.005           Do
      4  ==  Csharp == Dflat       69.296    138.591    277.183    554.365   1108.731   2217.461           Do diese  == Re bemol
      5  ==  D                     73.416    146.832    293.665    587.330   1174.659   2349.318           Re
      6  ==  Dsharp == Eflat       77.782    155.563    311.127    622.254   1244.508   2489.016           Re diese  == Mi bemol
      7  ==  E                     82.407    164.814    329.628    659.255   1318.510   2637.020           Mi
      8  ==  F                     87.307    174.614    349.228    698.456   1396.913   2793.826           Fa
      9  ==  Fsharp == Gflat       92.499    184.997    369.994    739.989   1479.978   2959.955           Fa diese  == Sol bemol
     10  ==  G                     97.999    195.998    391.995    783.991   1567.982   3135.963           Sol
     11  ==  Gsharp == Aflat      103.826    207.652    415.305    830.609   1661.219   3322.438           Sol diese == La bemol

      Examples of various scales (Root = "C")
      ---------------------------------------
      Name                C   Db   D   Eb   E   F   Gb   G   Ab   A   Bb   B   C
                              C#       D#           F#       G#   A   A#
      Major               1    .   2    .   3   4    .   5    .   6    .   7   1
      Minor (natural)     1    .   2    3   .   4    .   5    6   .    7   .   1
      Harmonic Minor      1    .   2    3   .   4    .   5    6   .    .   7   1
      Melodic Minor Asc   1    .   2    3   .   4    .   5    .   6    .   7   1
      Melodic Minor Desc  1    .   2    3   .   4    .   5    6   .    7   .   1
      Enigmatic           1    2   .    .   3   .    4   .    5   .    6   7   1
      Chromatic           1    2   3    4   5   6    7   8    9  10   11  12   1
      Diminished          1    .   2    3   .   4    5   .    6   7    .   8   1
      Whole Tone          1    .   2    .   3   .    4   .    5   .    6   .   1
      Pentatonic Major    1    .   2    .   3   .    .   4    .   5    .   .   1
      Pentatonic Minor    1    .   .    2   .   3    .   4    .   .    5   .   1
      3 semitone          1    .   .    2   .   .    3   .    .   4    .   .   1
      4 semitone          1    .   .    .   2   .    .   .    3   .    .   .   1
      ...

Documentation in '..\Function\factorial.hdr'

     Functions     factorial(n)             The factorial of n, i.e. n!  Return a long long integer.
                   log_factorial(n)         The natural log of the factorial of n. Return a double float.

Documentation in '..\Function\gaussian.hdr'

     gaussian,  pdf of the normal distribution

           the function  'gaussian(<x>, <mu>, <sigma>)'
           where <mu>     is the mean
                 <sigma>  is the standard deviation

Documentation in '..\Function\hailstone_number.hdr'

     Usage:    next_hailstone_number(n)

     The Collatz conjecture is a conjecture in mathematics named after Lothar Collatz, who first proposed it in 1937.

     The conjecture can be summarized as follows. Take any positive integer n. If n is even, divide it by 2 to get n/2.
     If n is odd, multiply it by 3 and add 1 to obtain 3n+1. Repeat the process (which has been called 'Half Or Triple Plus One',
     or HOTPO) indefinitely. The conjecture is that no matter what number you start with, you will always eventually reach 1.

Documentation in '..\Function\halton.hdr'

     NAPA mathematical function:  "halton"

     USAGE:    halton(index, n)
               Returns a 'double'.
               Returns a QUASI random number uniformly distributed on [0.0, 1.0].

               where <index>  is a the index of the sequence
                     <n>      is the nth number in the list of the first 100 prime numbers

     Quasi-random numbers are sometimes preferred to pseudo-random numbers
     because they are more uniformly distributed over the interval (0,1).

     Example of Use:  To populate a bi-dimensional space, use two different prime numbers to generate the values for X and Y axis:

                      for X:     halton(LOOP_INDEX, 1)
                      for Y:     halton(LOOP_INDEX, 2)

     Warning:         Verify the distribution in the space (X-Y plot on N data).
                      Use also the user tool 'lag' from file 'lag0.hdr'.

Documentation in '..\Function\isign.hdr'

     Function 'isign(x,y)' and macro 'ISIGN(x,y)'   transfer of sign from 'y' to 'x',  returns new 'x'. 'x' and 'y' do not change.

Documentation in '..\Function\limiter.hdr'

      Symmetrical Limiter Functions    hard_limiter(x, a)             a >= 0.0
                                       soft_limiter(x, a, b)          a >= 0.0, b >= 0.0
                                       smooth_limiter(x, a, b)        a >= 0.0, b >= 0.0

                      ............... a            Hard
                      .
                      .
                      .
        - - - - - - - 0 - - - - - - - - - > x
                      .
                      .
      -a ..............         hard_limiter(x, a) == soft_limiter(x, a, 0.0)

                          ........... a            Soft
                         .:
                        . :
                 -b    .  :
        - - - - - - - - - - - - - - - - - > x
                   : .    b
                   :.
      -a ..........:

      Please note that these limiters are introducing non linearities in the amplitude but does not introduce any phase shift.
      Accurate simulation of amplifier non linearities requires phase shift.

Documentation in '..\Function\logn.hdr'

     Function 'logn(x,n)',  Macro 'LOGN(x,n)'        logarithm in base n

Documentation in '..\Function\math.hdr'

     Functions 'GCD()', 'LCM()', max_prime_factor()

     USAGE:

      GCD(n1, n2)                            Greatest Common Divider of n1 and n2
      LCM(n1, n2)                            Least Common Multiple  of n1 and n2
      max_prime_factor(n)                    Find the greatest prime factor of the integer n

     Optional directive:

      GCD_ALGORITHM  to select GCD algorithm    ( 0 -> Euclid (default) ,  1 -> Binary )

Documentation in '..\Function\mean.hdr'

     Mean Functions and macros

        "A"  ->   arithmetic_mean(a,b)              ARITHMETIC_MEAN(a,b)
        "M"  ->   arithmetic_geometric_mean(a,b)    ARITHMETIC_GEOMETRIC_MEAN(a,b)
        "g"  ->   centroidal_mean(a,b)              CENTROIDAL_MEAN(a,b)
        "c"  ->   contraharmonic_mean(a,b)          CONTRAHARMONIC_MEAN(a,b)
        "G"  ->   geometric_mean(a,b)               GEOMETRIC_MEAN(a,b)
        "H"  ->   harmonic_mean(a,b)                HARMONIC_MEAN(a,b)
        "h"  ->   heronian_mean(a,b)                HERONIAN_MEAN(a,b)
        "r"  ->   root_mean_square(a,b)             ROOT_MEAN_SQUARE(a,b)

           NB:  The 3 Pythagorean means are the arithmetic mean, the geometric mean and the harmonic mean.
                Relationship:   A >= G >= H

      - The ARITHMETIC MEAN, "A", of real numbers "a" and "b" is defined as:                   A = (a + b)/2
                The arithmetic mean is also known as the arithmetic average.

      - The ARITHMETIC_GEOMETRIC MEAN, "M", of real numbers "a" and "b" is computed by an
        algorithm involving the successive application of arithmetic and geometric means.

      - The CENTROIDAL MEAN, "g", of real numbers "a" and "b" is defined as:                   g = (2/3)(a^2 + ab + b^2)/(a + b)

      - The CONTRAHARMONIC MEAN, "c", of real numbers "a" and "b" is defined as:               c = (a^2 + b^2)/(a + b)
                The contraharmonic mean is also known as the antiharmonic mean.
                Relationship with the Pythagorean means:   c >= A >= G >= H

      - The GEOMETRIC MEAN, "G", of real numbers "a" and "b" is defined as:                    G = sqrt(a*b)

      - The HARMONIC MEAN, "H", of real numbers "a" and "b" is defined as:                     H = 2*a*b/(a + b)

      - The HERONIAN MEAN, "h", of real numbers "a" and "b" is defined as:                     h = (a + sqrt(a*b) + b)/3
                The Heronian mean is a weigthed function of arithmetic and geometric mean,     h = (2*A + G)/3
                It is used in the computation of the volume of pyramidal frustum.
                Relationship with the Pythagorean means:   A >= h >= G >= H

      - The ROOT-MEAN-SQUARE MEAN "r", of real numbers "a" and "b" is defined as:              r = sqrt((a^2 + b^2)/2)
                The root-mean-square mean is also known as the quadratic mean.

Documentation in '..\Function\mu_law.hdr'

      Mu-Law Companding Functions.

      y = compress_mu_law(x)       -1.0 <= x <= 1.0
      x =   expand_mu_law(y)       -1.0 <= y <= 1.0

      MU_CONSTANT     255.0                          North American and Japanese Standards

Documentation in '..\Function\powerof.hdr'

     Power of long long INTEGER numbers

       Functions 'powerof()',   'ispowerof()'        Macros   'POWEROF()',   'ISPOWEROF()'
       Functions 'powerof2()',  'ispowerof2()'       Macro                   'ISPOWEROF2()'
       Functions 'powerof10()', 'ispowerof10()'      Macros   'POWEROF10()', 'ISPOWEROF10()'

       Usage:     n = powerof(num,exp)        ->  num^exp
                  n = powerof2(exp)               equivalent to  powerof( 2,exp)
                  n = powerof10(exp)              equivalent to  powerof(10,exp)

                  n = POWEROF(num,exp)        ->  num^exp
                  n = POWEROF10(exp)              equivalent to  POWEROF(10,exp)

                  where 'exp' is positive

                  b = ispowerof(base,num)
                  b = ispowerof2(num)             equivalent to  ispowerof( 2,num)
                  b = ispowerof10(num)            equivalent to  ispowerof(10,num)

                  b = ISPOWEROF(base,num)
                  b = ISPOWEROF2(num)             equivalent to  ISPOWEROF( 2,num)
                  b = ISPOWEROF10(num)            equivalent to  ISPOWEROF(10,num)

                  where 'base' is strictly positive

Documentation in '..\Function\print_var_and_string.hdr'

     Macros functions with output on 'stderr' and, with 'directive LOGFILE', also on log file:
     These macros are enabled with  'directive PRINTVAR' and disabled with  'directive NOPRINTVAR'        (default is 'PRINTVAR')

         'print_var(v,u)'                  prints the value of a numeric variable 'v' and its unit 'u'
         'print_dvar(v,u)'                 prints the value of an analog variable 'v' and its unit 'u'
         'print_ivar(v,u)'                 prints the value of a digital variable 'v' and its unit 'u'
         'print_var_and_string(v, u, s)'   prints the value of a numeric variable 'v', its unit 'u' and the value of string 's'
         'print_dvar_and_string(v, u, s)'  prints the value of an analog variable 'v', its unit 'u' and the value of string 's'
         'print_ivar_and_string(v, u, s)'  prints the value of a digital variable 'v', its unit 'u' and the value of string 's'
         'print_string(s)'                 prints the value of a string 's'

         'print_line_of_stars(n)'          prints a line of n stars
         'print_line_of_chars(n, c)'       prints a line of n characters 'c'
         'print_blank_line()'
         'print_newline()'

     EXAMPLES:
         ...
         dvar    foo   DB2LIN(60.0, 1.0)
         string  msg   "Example"
         init   void   print_dvar_and_string(foo, "dB", "volt peak")
         init   void   print_var(foo, "dB")
         init   void   print_ivar(npts, "")
         init   void   print_blank_line()
         init   void   print_newline()
         init   void   print_line_of_stars(80)
         init   void   print_line_of_chars(32, '-')
         init   void   print_string(msg)
         init   void   print_string("my message")
         init   void   print_string(join_2_strings("Current use case: ", msg))
         ...

Documentation in '..\Function\prompt.hdr'

     Functions  'prompt_for_double()'
                'prompt_for_long_long()'
                'prompt_for_long()'

                'prompt_for_yes_no()'

     Simulation stops until an answer is typed on keyboard, data type is checked.

     Examples:  dvar  lin_ampl    DB2LIN(prompt_for_double("Enter the amplitude in dB"), 1.0)
                ivar  npts               prompt_for_long_long("Enter the number of points")
                ivar  answ               prompt_for_yes_no("Short simulation?")

Documentation in '..\Function\QR.hdr'

     NAPA mathematical functions producing QUASI-RANDOM variates
           "QR_01", "QR_01_x", "QR_uniform", "QR_uniform_x",
           "QR_gaussian", "QR_normal"

     Based on the quasi-random generating function  "halton(index,dimension)".
     Consult documentation in "../Function/halton.hdr".

     from CONTINUOUS distributions (double float output)

     Generator                           Range (x)        Mean          Variance

     QR_01(index,dimension)              0 <= x <= 1      1/2           1/12
     QR_01_x(index,dimension)            0 <  x <  1      1/2           1/12
     QR_uniform(a,b,index,dimension)     a <= x <= b      (a+b)/2       (b-a)*(b-a)/12
     QR_uniform_x(a,b,index,dimension)   a <  x <  b      (a+b)/2       (b-a)*(b-a)/12

     QR_gaussian(s,index,dimension)      all x            0.0           s*s
     QR_normal(m,s,index,dimension)      all x            m             s*s

Documentation in '..\Function\random.hdr'

     Functions generating random variates:

     ............ from DISCRETE distributions (long integer output) ............

     Generator                    Range (i)     Mean           Variance

     rand_bernoulli(p)            0,1           p              p*(1-p)
     rand_binomial(n,p)           0,...,n       n*p            n*p*(1-p)
     rand_equilikely(a,b)         a,...,b       (a+b)/2        ((b-a+1)*(b-a+1)-1)/12
     rand_geometric(p)            0,...         p/(1-p)        p/((1-p)*(1-p))

     rand_pascal(n,p)             0,...         n*p/(1-p)      n*p/((1-p)*(1-p))
     rand_poisson(m)              0,...         m              m

     ........... from CONTINUOUS distributions (double float output) ...........

     Generator                    Range (x)     Mean             Variance

     rand_01()                    0 <= x <= 1   1/2              1/12
     rand_01_x()                  0 <  x <  1   1/2              1/12

     rand_chisquare(n)            x > 0         n                2*n
     rand_erlang(n,b)             x > 0         n*b              n*b*b
     rand_exponential(m)          x > 0         m                m*m

     rand_gaussian(s)             all x         0.0              s*s

     rand_halfnormal(t)           x > 0         t*sqrt(2/Pi)     t*t*(1-2/Pi)

     rand_lognormal(m,s)          x > 0         exp(m+0.5*s*s)   (exp(s*s)-1)*exp(2*m+s*s)

     rand_normal(m,s)             all x         m                s*s

     rand_rayleigh(b)             x > 0         b*sqrt(Pi/2)     b*b*(4-Pi)/2

     rand_uniform(a,b)            a <= x <= b   (a+b)/2          (b-a)*(b-a)/12
     rand_uniform_x(a,b)          a <  x <  b   (a+b)/2          (b-a)*(b-a)/12

     See for instance:
       Handbook of Mathematical Functions With Formula, Graphs, and Mathematical Tables, page 930
       Edited by Mylton Abramowitz and Irene A. Stegun, National Bureau of Standards 1964
       reprinted Dover Publications, 1965

     REMARKS:

     Initialization is built-in in the C code produced by the NAPA compiler:   function 'napa_seed(long)'

     It means that these random numbers follow the same stream of random numbers as the NAPA node 'noise'. Therefore seed can be
     controlled by NAPA instruction 'random_seed'.

     These functions depend on the value of the macro ANTITHETIC which is controlling
     the internal random generator of NAPA through the macro function RAND_01().

     BOX_MULLER transformation is used to produce rand_gaussian, rand_normal(..) ..
     It is nevertheless possible to use the ODEH-EVANS (also known as the MARSAGLIA algorithm):

     directive  GAUSSIAN_ALGORITHM  BOX_MULLER_ALGORITHM                     (default)
     directive  GAUSSIAN_ALGORITHM  ODEH_EVANS_ALGORITHM

Documentation in '..\Function\reldif.hdr'

     Function 'reldif(a,b)'     computes the relative difference between R_TYPE numbers.
     Useful for comparison of double float numbers.

Documentation in '..\Function\rnoise.hdr'

     Noise in a resistor

     Macro     'RNOISE()'
     Function  'rnoise()'

     USAGE:    RNOISE(R,T)  or  rnoise(R,T)          (rms/Hz^0.5)

               where R is the resistance and T the absolute temperature

Documentation in '..\Function\round.hdr'

     Function 'round_it()'

     USAGE:

      round_it(x, ndigits)          Round x to (n+1) significant decimal digits

Documentation in '..\Function\rswitch.hdr'

     Functions  rswitch12(), rswitch123(), rswitch1234()  and  macro RSWITCH()

     Function rswitch12(nloop,r1,r2)           2 phases resistive switch, period is 2*nloop:   r1 r2   r1 r2   r1 r2   r1 r2  ...
     Function rswitch123(nloop,r1,r2,r3)       3 phases resistive switch, period is 3*nloop:   r1 r2 r3   r1 r2 r3   r1 r2 r3 ...
     Function rswitch1234(nloop,r1,r2,r3,r4)   4 phases resistive switch, period is 4*nloop:   r1 r2 r3 r4   r1 r2 r3 r4   r1 ...

     !!! IMPORTANT !!!
     The period of the clock controlling theses switches does NOT depend on the local sampling frequency FSL but on the
     frequency FS defined by instruction 'fs' in the netlist. This function is therefore location independant and does not
     depend on any decimation, interpolation, drop instructions ...

     Example for nloop = 3

        LOOP_INDEX         0   1   2   3   4   5   6   7   8   9  10  11  12  13  14  15  16  17  18  19  20   ...

                          <-------------------->  <-------------------->  <-------------------->  <---------
        rswitch12()       r1  r1  r1  r2  r2  r2  r1  r1  r1  r2  r2  r2  r1  r1  r1  r2  r2  r2  r1  r1  r1   ...

                          <-------------------------------->  <-------------------------------->  <---------
        rswitch123()      r1  r1  r1  r2  r2  r2  r3  r3  r3  r1  r1  r1  r2  r2  r2  r3  r3  r3  r1  r1  r1   ...

                          <-------------------------------------------->  <---------------------------------
        rswith1234()      r1  r1  r1  r2  r2  r2  r3  r3  r3  r4  r4  r4  r1  r1  r1  r2  r2  r2  r3  r3  r3   ...

     Macro RSWITCH(clk,ron,roff) selects the switch resistance depending on binary clock state 'clk'.

        clk = 0,  output is roff
        clk = 1,  output is ron

Documentation in '..\Function\serie_parallel.hdr'

     Functions 'serie_R(), serie_C(), serie_L(), parallel_R(), parallel_C(), parallel_L()'

Documentation in '..\Function\sinc.hdr'

      UNNORMALIZED SINC FUNCTION  (sinus cardinalis)   sinc(x)      = sin(x)/x
        NORMALIZED SINC FUNCTION  (sinus cardinalis)   sinc_norm(x) = sin(pi*x)/(pi*x)

Documentation in '..\Function\stop_request.hdr'

     Function SET_STOP_REQUEST() and STOP_REQUEST()

       Use in instruction 'terminate' to trigger the end of a simulation from an algebra node, a user function, a tool
       or the update of a variable. The function STOP_REQUEST() does not need to be initialised and output 'false' until
       one or several SET_STOP_REQUEST().

       EXAMPLE :

       ***** Header file "myfun.hdr" ********************************************

         ...
         #include "/Simulate/Napados/Hdr/Function/stop_request.hdr"
         ...
         void    check_duser_myfun(..., int);
         void     init_duser_myfun(..., int);
         void    reset_duser_myfun(..., int);
         void    close_duser_myfun(..., int);
         R_TYPE        duser_myfun(..., int);
         ...
         R_TYPE  duser_myfun(..., int id) 
           double out;
           ...
           if (...) 
             SET_STOP_REQUEST();       // latches output of STOP_REQUEST() to 'true'
           
           ...
           return out;
         
         ...

       **************************************************************************

       ***** NAPA netlist "mytest.nap" ******************************************

         ...
         header <napatool.hdr>
         ...
         node  s1  duser myfun ....                           <-- use conditionnaly a SET_STOP_REQUEST() to ask for a stop
         ...               |
         ...               |
         ...               +----------------+
         ...                                |
         ...                                v
         terminate (1000<LOOP_INDEX) || STOP_REQUEST()       <-- STOP_REQUEST() returns 'false' until SET_STOP_REQUEST() is called
         ...

       **************************************************************************

Documentation in '..\Function\switch.hdr'

      Functions selecting an input between 2 inputs

       i = switch_i(m, i0, i1)      I_TYPE,  returns i0 if (0 == m), i1 otherwise
       d = switch_d(m, d0, d1)      R_TYPE,  returns d0 if (0 == m), d1 otherwise

      EXAMPLE in a NAPA netlist:

          node  clk  clock "01"

          dvar  Roff 1.0e9
          dvar  Ron  1.0

          dvar  rsw  switch_d(clk, Roff, Ron)
                               |     |    |
                               |    (0)  (!0)
                               |_____|____|

      For multiple choices, ie. more than 2, use functions 'choice_between_i()' or 'choice_between_d()'

Documentation in '..\Function\thermometric.hdr'

      Convert an integer to a N bit equivalent thermometric code

      USAGE:thermometric(value, nbit)   where value is in [0..nbit]
                                              nbit  is in [1..  64]

            returns an unsigned long integer

      Example, for nbit = 8

       0    ->    00000000000000000000000000000000     i.e.    000    or   0X00
       1    ->    00000000000000000000000000000001     i.e.    001    or   0X01
       2    ->    00000000000000000000000000000011     i.e.    003    or   0X03
       3    ->    00000000000000000000000000000111     i.e.    007    or   0X07
       4    ->    00000000000000000000000000001111     i.e.    015    or   0X0F
       5    ->    00000000000000000000000000011111     i.e.    031    or   0X1F
       6    ->    00000000000000000000000000111111     i.e.    063    or   0X3F
       7    ->    00000000000000000000000001111111     i.e.    127    or   0X7F
       8    ->    00000000000000000000000011111111     i.e.    255    or   0XFF

Documentation in '..\Function\time.hdr'

     Macro function 'SYSTEM_TIME()'     to be used to get computer system time.
     Return a double.

     See also file "../Resource/clock.hdr"

Documentation in '..\Function\vandercorput.hdr'

     NAPA mathematical function:  "vandercorput"

     USAGE:  vandercorput(n,b)

          where n is the index number  [0, inf[
                b is the base          [2, inf[

          0.0  <=  vandercorput(n,b)  <= 1.0

     van der Corput sequences are a means of generating sequences of points that are maximally self-avoiding (a.k.a. quasirandom
     sequences). Like quasirandom sequences, "permuted" van der Corput sequences are constrained by a low-discrepancy requirement,
     which has the net effect of generating points in a highly correlated manner (i.e., the next point "knows" where the previous
     points are).

     The concept of low-discrepancy is associated with the property that the successive numbers are added in a position as away
     as possible from the others numbers, that is, avoiding clustering (groups of numbers close to other). The sequence is
     constructed based in the schema that each point is repelled from the others. So, if the idea for the points is maximally
     avoiding of each other, the job for the numbers generated sequentially is to fill in the larger "gaps" between the previous
     numbers of the sequence.

     For example, the ordinary van der Corput sequence in base 3 is given by
          0, 1/3, 2/3, 1/9, 4/9, 7/9, 2/9, 5/9, 8/9, 1/27, ...

Documentation in '..\Function\vt.hdr'

     Thermal Voltage  Vt,  kt

     Macro     'VT()', 'KT()'
     Function  'vt()', 'kt()'

     USAGE:   VT(T)  or  vt(T)     to compute kT/q   from T (Kelvin)
              KT(T)  or  kt(T)     to compute kT     from T (Kelvin)

              VT(TEMPERATURE_K) and KT(TEMPERATURE_K) are using the temperature defined in file "./napa.hdr"
              or the temperature defined in the simulation when it is overwritten by a user directive.

              see functions from  file "./convert3.hdr" for temperature conversions.

     The function vt() and kt() are resp. equivalent to the macros VT() and KT().
     They offer an extra check thanks to ANSI-C prototyping.

Documentation in '..\Function\weight_random.hdr'

     Pairs of functions:  parm_for_rand_uniform(       low,high)
                          weight_of_rand_uniform(parm, low,high)

                          parm_for_rand_normal(       mean,sigma)
                          weight_of_rand_normal(parm, mean,sigma)

                          parm_for_rand_rayleigh(       b)
                          weight_of_rand_rayleigh(parm, b)

                x = parm_for_rand_normal(m,s)                                  w = weight_of_rand_normal(x,m,s)
                                                                                         . .
        dp |      parameter x randomly chosen                         dp |             .     .      weight w corresponding to x
           |      in a span determined by SPREAD                         |           .w        .    in the specified distribution
           |            |                                                |         .  ^          .
           |            |                                                |            |
           |     -------|---------------                                 |       .    |            .
           |     :      |              :  uniform distribution           |     .      |              .  normal distribution
           |     :      |              :                                 |  .  [      |              |  .
           |_____|______v___|__________|____________                     |_____|______|___|__________|____________
             -SPREAD*s  x   m      +SPREAD*s                               -SPREAD*s  x   m      +SPREAD*s

                 <---span of analysis-->                                       <---span of analysis-->

     Value <x> and corresponding weight <w> are used to build weighted histograms by producing a random uniformly distributed
     variable and its probability of occurrence corresponding to the distribution to be simulated. This is useful to get a chance
     to analyze samples at the edge of the normal distribution.

         **** Example ****

         header <napatool.hdr>
         fs     1.0e6

         dvar   n1  parm_for_rand_normal(2.0, 0.1)
         update n1  when  nxt
         dvar   w1  weight_of_rand_normal(n1, 2.0, 0.1)     //  corresponds to the weight of the value of n1 in context
         update w1  when  nxt

         dvar   n2  parm_for_rand_uniform(-7.0, 0.8)
         update n2  when  nxt
         dvar   w2  weight_of_rand_uniform(n2, -7.0, 0.8)   //  corresponds to the weight of the value of n2 in context
         update w2  when  nxt

         dvar   n3  parm_for_rand_normal(-7.0, 0.8)
         update n3  when  nxt
         dvar   w3  weight_of_rand_normal(n3, -7.0, 0.8)    //  corresponds to the weight of the value of n3 in context
         update w3  when  nxt

         dvar    w  w1*w2*w3                                //  weight corresponding to the cumulated weights w1, w2 and w3
         update  w  when  nxt

         event nxt  (new) TOOL_INDEX

         ... ( computation of x )

         tool   w_histogram   "w_histo.out"    x 1.0   w 100000                //   weighted histogram
         tool   w_statval     "w_statval.out"  x 1.0   w 100000                //   statistics

         terminate 5 <= TOOL_INDEX

     Directive:   SPREAD      <Double_Float_Number>
     This directive is used to set the range of the normally distributed variable    (default is 6, for +/- 6 sigma).

NAPA user defined functions

Documentation in '..\User\arithmetic.hdr'

     NAPA duser defined function:   "arithmetic_average"
     NAPA iuser defined function:   "arithmetic_average"

     Moving Arithmetic Average (analog or digital). It is equivalent to a FIR with a rectangular weighting.

          0  ___   1  ___   2       ___  num-1
            |   |    |   |         |   |
     in --+-|del >-+-|del >-+- .. -|del >-+
          | |___|  | |___|  |      |___|  |
          |        |        |             |    __________________________
          |        |        |             |   |                          |
          +-------(+)------(+)-----------(+)--| 1 / (num * scale_factor) |--> out
                                              |__________________________|

     Software implementation of the delay chain: a rolling table
               _____________
              |             |
            0 |             |
              |_____________|     new_data    = in
              |             |     running_sum = running_sum - oldest_data + new_data
            1 |             |
              |_____________|     arithmetic_average = running_sum / (num * scale_factor)
              |             |
              :             :
              |_____________|
              |             |
          c-1 | newest_data |          :
              |_____________|          :
              |             |
            c | oldest_data |<--- rolling_index ---.
              |_____________|                       \
              |             |          :             \
              :             :         \ /             \
              |_____________|          .               \
              |             |                           \
        num-1 |             |                            \____ in
              |_____________|

     USAGE:

       node <output_node>  duser arithmetic_average <input_node>  <num>  <scale_factor>
       node <output_node>  duser arithmetic_average <input_node>  <num>

       node <output_node>  iuser arithmetic_average <input_node>  <num>  <scale_factor>
       node <output_node>  iuser arithmetic_average <input_node>  <num>

       where  <input_node>    is the  input node of the moving arithmetic average filter
              <output_node>   is the output node of the moving arithmetic average filter
              <num>           is the number of data to average                  @ init
              <scale_factor>  is an optional scale factor  (default 1)          @ init

       <scale_factor> is a real (duser function) or a long (iuser function).

     Debug mode:    no specific directive

Documentation in '..\User\coherentwave.hdr'

      Coherent sinewave

        This function precomputes, or reuses if possible, tables of sine.

        node <nod> duser coherentwave                 <target_freq> <target_phase>  <npts>
        node <nod> duser coherentwave <offset> <ampl> <target_freq> <target_phase>  <npts>

        where:  <nod>          is the output node
                <offset>       is the DC offset          (default is 0.0)
                <ampl>         is the amplitude peak     (default is 1.0)
                <target_freq>  is the target to compute coherent frequency (Hz)         @ init
                <target_phase> is the target to compute phase              (radian)     @ init
                <npts>         is the number of data for coherence                      @ init

        NB:  Phase should be in interval [0, 2pi] radian.
             Effective phase is depending on the granularity of the precomputed table.

        It has a clear speed advantage to 'sine'  -ONLY IF-  there are multiple uses of coherent waves with the SAME number of
        points in a simulation.

      Debug mode:    COHERENT_WAVE

Documentation in '..\User\comb.hdr'

     Rectangular Comb Generator,  multitone signal

         >>>  This generator is -NOT- intended to be used for coherent sampling, see file "multitone.hdr".

     NAPA duser defined function:  "comb"

     USAGE:
        node <nod> duser comb <offset> <amplmax>                 <numfreq>  <(opt)>
        node <nod> duser comb <offset> <amplmax>  <bandwidth>    <numfreq>  <(opt)>
        node <nod> duser comb <offset> <amplmax>  <fmin> <fmax>  <numfreq>  <(opt)>

        where:   <nod>       is the output node
                 <offset>    is the DC offset                                   (   reset)
                 <amplmax>   is the max amplitude guaranteed, see below.        (   reset)
                 <bandwidth> is the bandwidth of the comb signal                (   reset)
                 <fmin>      is the min freq of the comb signal                 (   reset)
                 <fmax>      is the max freq of the comb signal                 (   reset)
                 <numfreq>   is the number of sinewaves in the comb signal      @ init

       (<opt>)   (linscale) or (logscale)          default scale is (linscale)  (optional)
                 (random), (schroeder) or (equal)  default phase is (random)    (optional)

                 Default value for <bandwidth> is  0 ... Nyquist.

     It produces a comb of <numfreq> sinewaves from <fmin> to <fmax> with random phase. Amplitude of resulting signal is never
     larger than (<offset> + <amplmax>) and never smaller than (<offset> - <amplmax>)  by construction.

     These sinewaves are produced from a set of RESONATORS to speed up as trigonometric functions are awfully long to compute!

     Each resonator produces a single sinewave and has the following structure:
                                      ______    ____
                              x[2]   |      |  |    |
                +--------------------| * -1  >-|    |
                |                    |______|  |    |   x[0]
                |                     ______   |sum  >--+
                |             x[1]   |      |  |    |   |
                |             +------| * k   >-|    |   |
                |             |      |______|  |____|   |
                |    ______   |       ______            |
                |   |      |  |      |      |           |
                +--< delay |--+--+--< delay |-----------+
                    |______|     |   |______|
                                 |
                                 +----------------------------> out

           Default option is (random) using random phase for each sinewaves at reset.
           Option (equal)     chooses the same random phase for all sinewaves at reset.
           Option (schroeder) uses a minimization technique to lower the crest factor, suited for linearly spaced frequencies!

           Crest Factor (aka PAR, Peak to Average Ratio) =  V Peak / V RMS

           NB:   Varying the phase difference between adjacent frequency tones linearly (schroeder) allows the creation of
                 multitone signals with very low crest factors. However, the resulting multitone signals have the following
                 potentially negative characteristics:

                     - The multitone signal is very sensitive to phase distortion. If the DUT induces non-linear phase distortion,
                       the crest factor might increase considerably.
                     - The multitone signal might display some repetitive time-domain characteristics.

                 Varying the tone phases randomly (random) results in a multitone signal whose amplitudes are nearly Gaussian in
                 distribution as the number of tones increases. In addition to being more noise-like, the signal also is much less
                 sensitive to phase distortion.

     Debug mode:    COMB

Documentation in '..\User\dem.hdr'

      DEM SIMULATOR:

      Simulates dynamic element matching (DEM). Simulator accepts either no DEM (thermometer), DWA, R2DWA or Full Randomization.

      node output  iuser dem  <input> <nlev>
      node output  iuser dem  <input> <nlev>  (<option>)

      input:          Integer [0..nlev]
      nlev:           Number of output levels [2..31]                      @ init
      (<option>):     Dynamic Element Matching Mode
                          (none)      No mismatch shaping                  (default)
                          (dwa)       First Order Data Weighted Averaging
                          (r2dwa)     Restricted Second Order Data Weighted Averaging
                          (random)    Full Random Data Weighted Averaging

      output:         Long integer representing the binary output.

             ...............................................
             :       ______________       ___________      :
             :      |              |     |           |     :
     nlev --->      |              |---->|           |-----:--> output:nlev-1
             :      | Binary to    |  .  |           |  .  :    .
             :      |              |  .  |           |  .  :    .
             :  b   | Thermometric |  .  | Scrambler |  .  :    .
     input --:--/-->|              |---->|           |-----:--> output:1
             :      | Encoder      |---->|           |-----:--> output:0
             :      |______________|     |___________|     :
             :                                             :
             :........................................dem..:

     Debug mode:    DEM

Documentation in '..\User\domain.hdr'

     NAPA duser defined functions:  "synchro_lindomain", "synchro_logdomain"

     USAGE:

     node <node_nam> duser synchro_lindomain <lim1> <lim2>
     node <node_nam> duser synchro_lindomain <lim1> <lim2> <rate>
     node <node_nam> duser synchro_lindomain <lim1> <lim2> <rate> <offset>

     node <node_nam> duser synchro_logdomain <lim1> <lim2>
     node <node_nam> duser synchro_logdomain <lim1> <lim2> <rate>
     node <node_nam> duser synchro_logdomain <lim1> <lim2> <rate> <offset>

     Where  lim1    limit min of interval [lim1, lim2].                         @ init
            lim2    limit max of interval [lim1, lim2].                         @ init
            rate    decimation rate of the trigger input, default 1.            @ init
            offset  offset of the decimation, default 0.                        @ init

     Output is randomly distributed in the interval   (lin or log distribution).

     Operations are SYNCHRONOUS to TOOL_INDEX: output may change when TOOL_INDEX changes.

     It means that if no tool is instantiated, this function will generate an error. See the tool 'synchro' designed to manage
     this situation.

     To redefine the trigger mechanism, use:   directive SYNCHRO_DOMAIN a_new_function.

     Be careful to choose an interval not including 0.0 or negative values for synchro_logdomain.

     EXAMPLE:  generate sinewave with random frequencies, make analysis and sort results.

     title   "RANDOM FREQUENCIES"
     header  <napatool.hdr>
     fs      1.0e6

     export freq

     node freq   duser  synchro_lindomain   1000.0  5000.0
     node out    sin    0.0  1.0  freq  0.0

     tool    sinewave "foo.out" out 1.0  100000            // unsorted results
     post    sort   "stdout"  8                            //   sorted results

     terminate   10 <= TOOL_INDEX

        >>>>>  What are the advantages of this method based on RANDOM numbers?

        Making a traditional sweep (1000.0, 1500.0, ..,  5000.0) of frequencies could cause very subtle problems. If the module
        under test is sensitive to aliasing, the simulation could exercise only too favorable cases making the analysis too
        optimistic or at least uncomplete.

        Using RANDOM numbers, we will destroy the regular pattern of frequencies, avoiding the consequences of possible aliasing.
        Results of the simulation are postprocessed to sort the results properly.

        Another usage of this method is to accumulate results over a long period of time (e.g. a week-end). The simulation is
        stopped (system break like ctr-C). No need to predict the duration of the simulation. More we wait, more results we get
        over the entire interval. Traditional sweep will produce less results or results on a truncated interval.

        These nodes should be preferred to functions 'lindomain' and 'logdomain' as they are automatically synchronized to the
        analysis tools (see file "control.hdr").

     Debug mode:    no specific directive

Documentation in '..\User\dpll.hdr'

      NAPA duser defined function:   "dpll"

      Digital input, Analog output, Charge-Pump PLL       (NB: Multiple output user's function)

                  .............................................................................................
                  : dpll   ____     ___________     ____     ____     _____           _____                   :
                  :       |    |   |           |   |    |   |    |   |     |      -->|  s  |                  :
       in -------->------>| :M |-->|           |   |    |   |    |   |     |         |  t  |                  :
                  :       |____|   |           |   |    |   |    |   |     |      -->|  o  |                  :
                  :        ____    | PD or PFD |-->| CP |-->| LF |-->| VCO |--+      |  r  |                  :
                  :       |    |   |           |   |    |   |    |   |     |  |      |  a  |                  :
                  :   +-->| :N |-->|           |   |    |   |    |   |     |  |   -->|  g  |                  :
                  :   |   |____|   |___________|   |____|   |____|   |_____|  |      |  e  |                  :
                  :   |                                                       |   -->|_____|                  :
                  :   +-------------------------------------------------------+         ^                     :
                  :                                                                     |         TAG = id    :
                  :                                          [instantiation id]---------+--------------------->-----+ tag
                  :                                                                                           :     |
                  :...........................................................................................:     |
                                                                                                                    |
                                                                                                                    |
                                                                                                                    |
            +-------------------------------------------------------------------------------------------------------+
            |
            |
            |     .............................................................................................
            |     . dpll                                                                                      :
            |     :                               TAG                                                         :
            +----->---------------------------------------------------------------------+       (otyp_i)      :
            |     :                                                                     |          |          :
            |     :                                                                   __v__      __v__        :
            |     :                                                                  |  s  |--->|     |       :
            |     :                                                                  |  t  |    |     |       :
            |     :    Select one output at a time, thanks to option                 |  o  |--->|     |       :
            .     :     (otyp_i) using the TAG provided by main instantiation        |  r  |    | mux |---+   :
            .     :                                                                  |  a  |    |     |   |   :
            .     :                                                                  |  g  |--->|     |   |   :
            v     :                                                                  |  e  |    |     |   +--->-----> out
                  :                                                                  |_____|--->|_____|       :
                  :                                                                                           :
                  :...........................................................................................:

      M   (Frequency Divider of the Reference Signal)
      N   (Frequency Divider of the Feedback  Signal)
      PFD (Phase Frequency Detector, Positive Edge)
      CP  (Charge Pump)
      LF  (Loop Filter)
      VCO (Voltage Controlled Oscillator)

      USAGE:

      node <tag>    duser  dpll  <in>  <M> <N>  <PFD_arr> <CP_arr> <LF_arr> <VCO_fil>              // main function
             |
             +---------------------+
                                   |
      node <out_1>  duser  dpll  <tag> (<otyp_1>)                                                  // refers to <tag> of 1st line!
      node <out_2>  duser  dpll  <tag> (<otyp_2>)                                                  // idem
      node <out_3>  duser  dpll  <tag> (<otyp_3>)   (P)                                            // idem
      node <out_4>  duser  dpll  <tag> (<otyp_4>)                                                  // idem
      ...
      node <out_n>  duser  dpll  <tag> (<otyp_n>)   (Q)                                            // idem

      <tag>             is the output of dpll main function which is used as reference to extract outputs.

      <in>              Digital square signal, reference signal  (0 or !0).

      <M>               Divider coefficient for the reference signal.  Integer >= 1.
      <N>               Divider coefficient for the feedback signal.   Integer >= 1.
                        These digital variables may be updated during the simulation to allow the modeling of fractional PLLs.

      <PFD_arr>         Array of pointers containing Phase Frequency Detector data:
                        -> svar    "PFD"                                                 @ init
                        -> ivar    number of PFD states                                  @ init
                        -> dvar    I to O delay of the PFD for the reference signal      @ init
                        -> dvar    I to O delay of the PFD for the feedback reference    @ init

                        >>> See file './Resource/pfd.hdr' for currently implemented PFD descriptions!

                        Example for a PFD:
                        ..
                        svar  type         "PFD"
                        ivar  states       -5                       //     five states, with an inverted transfer function
                        dvar  delay_sig    4.0e-9                   //     second
                        dvar  delay_ref    6.0e-9                   //     second
                        ganging  PFD_arr[] type  states  delay_sig delay_ref
                        ..

      <CP_arr>          Array of pointers containing Charge Pump data (2 to 7 currents):
                        These currents may be updated during the simulation.

                        # states      2    3    4    5    6    7

                        -> dvar      ..   ..   ..   ..  im3  im3        (more negative)
                        -> dvar      ..       im2  im2  im2  im2
                        -> dvar     im1  im1  im1  im1  im1  im1
                        -> dvar      ..  iz0   ..  iz0   ..  iz0
                        -> dvar     ip1  ip1  ip1  ip1  ip1  ip1
                        -> dvar      ..   ..  ip2  ip2  ip2  ip2
                        -> dvar      ..   ..   ..   ..  ip3  ip3        (more positive)

                        Example for a set of 5 current sources:
                        ..
                        dvar  im2  -3.2e-6    //  negative current high,   Ampere
                        dvar  im1  -2.4e-6    //  negative current low,    Ampere
                        dvar  iz0   1.0e-9    //  zero     current,        Ampere
                        dvar  ip1   2.6e-6    //  positive current low,    Ampere
                        dvar  ip2   3.1e-6    //  positive current high,   Ampere
                        ganging  CP_arr[]     im2 im1  iz0  ip1 ip2
                        ..

      <LF_arr>          Array of pointers containing Loop Filter data:

                        -> dvar    Laplace Domain description of the Loop Filter  N0..Nn D0..Dn  of the equation:

                                          N0 + N1*s + N2*s^2 + ... + Nn*s^n
                                   H[s] = ---------------------------------      ( @ init)
                                          D0 + D1*s + D2*s^2 + ... + Dn*s^n

                                   The order of the denominator should be larger or equal to the order of the numerator.

                        Example of Loop Filter:   (input is the current delivered by the charge pump, output is the VCO control)
                        ..
                        dvar  C1   8.20e-12               //     in (I) ---+------+---> out (V)
                        dvar  R2   23.0e3                 //               |      |
                        dvar  C2   82.0e-12               //               |      |
                                                          //               |     | |
                        dvar  N0   1.0                    //               |  R2 | |                       1.0 + (R2*C2)*s
                        dvar  N1   R2*C2                  //               |     | |          H[s] = --------------------------
                        dvar  N2   0.0                    //               |      |                  (C1+C2)*s + (R2*C1*C2)*s^2
                                                          //               |      |
                        dvar  D0   0.0                    //             =====  =====
                        dvar  D1   C1+C2                  //           C1  |      | C2
                        dvar  D2   R2*C1*C2               //              _|_    _|_

                        ganging  LF_arr[]  N0..2  D0..2   // these parameters must be described in this order!
                        ..

                        You can to include parasitics elements in description, like the input capacitance of the VCO module, and

                        For information, the transfer function including the output conductance G0 of the source and the input
                        capacitance C3 of the VCO is

                                                1.0 + (R2*C2)*s
                        H[s] =  --------------------------------------------------
                                G0 + ((C2*G0*R2)+C1+C2+C3)*s + (R2*C2*(C1+C3))*s^2

      <VCO_fil>         Name of file where are placed several couples of numbers to describe the transfer function of the VCO
                        (freq = function[volt]). The number of couples is not limited. Data in first column should be monotonic.
                        A third column may be provided with data about the power consumption of the VCO.
                        By default, a Catmull-Rom spline interpolation is used (see directive below) for the frequency and the
                        power estimation from the VCO file.

                        Example 1:   file "VCO_fil" without power information

                        # VCO TRANSFER FUNCTION, EXAMPLE OF DATA FILE
                        #
                        # VOLTAGE_IN    FREQUENCY_OUT
                          0.00           0.1e6
                          1.60          16.0e6
                          4.80          48.0e6
                          5.00          52.0e6

                        Example 2:   file "VCO_fil" with power information

                        # VCO TRANSFER FUNCTION, EXAMPLE OF DATA FILE WITH POWER DATA
                        #
                        # VOLTAGE_IN    FREQUENCY_OUT     POWER
                          0.00           0.1e6           5.2e-6
                          1.60          16.0e6          35.0e-6
                          4.80          48.0e6          85.0e-6
                          5.00          52.0e6         100.0e-6

                        Catmull-Rom Spline: Although cusps could happen in such splines, there is no risk here as a VCO transfer
                        function is well behaved. Still, a sanity check for the monotonicity of the interpolated transfer function
                        is made during the initialization of the simulation.

      <out_i>           Output signal according to one of the following options:

      (<otyp_j>)        @ init
                          (sinewave)       Analog VCO output with amplitude fixed to 1.0 peak.             (option by default)
                          (frequency)      Frequency of the signal on the VCO output.
                          (phase)          Phase of the signal on the VCO output.
                          (control)        Output voltage of the loop filter, which is also the voltage control of the VCO.
                          (lock)           Locking signal.
                          (synchro)        Divider output rising edges.

                        If VCO power data has been provided in VCO file:
                          (energy)         Estimation of energy dissipated in the VCO from the beginning of the simulation.
                          (power)          Estimation of average power dissipated in the VCO.

                        Due to the algorithm, some states occuring inside a computing period, although correctly simulated,
                        cannot be output as they are 'hidden' in the function.
                          (state)          Output of the PFD.
                          (current)        Output current of the charge pump.

      (P), (Q)          2 outputs in quadrature,  (P) is the option by default                             @init
                        Output (P) is used by the dpll internal feedback loop, output (Q) has a phase of (P) + Pi/2.

          This function is not compatible with short form '&delayed', add an external delay.

      Debug mode:    DPLL                           highly recommended
                     DPLL_VCO                       produce a file to verify the VCO interpolator behavior
                     DPLL_PFD                       debugging a users's pfd description

      Directives:    DPLL_VCO_SPLINE     <I>        <I> = 0:   Linear Interpolation
                                                    <I> = 1:   Catmull-Rom Spline Interpolation              (default      )
                     DPLL_STEP_DIVISION  <NNN>      precision of the zero crossing determination             (default 10000)
                     DPLL_PFD_LIB                   refer to a user's PFD file (see below)

     For ADVANCED USERS:

       It is possible to point to your own PFD modules, by using:

         directive DPLL_PFD_LIB  "myfile.hdr"                   (default: "../Resource/pfd.hdr")

         the type (PFD, ...), the number of states and the state machine can be described in this file.

Documentation in '..\User\dsinc.hdr'

     NAPA duser defined functions:  "dsinc"

     USAGE: node <output_node> duser dsinc <input_nod> <sinc_order> <decim>

     Where  <output_node>   is the output node
            <input_nod>     is the input node
            <sinc_order>    is the order of the sinc filter                     @ init
            <decim>         is the decimation factor                            @ init

     The I/O nodes are double precision, and the output is computed each time, even when decimating.

     This high level model uses a structure allowing to decimate AFTER the SINC filter. It simplifies the description and is
     equivalent to the practical realization where numerator section is separated from decimation section by the decimator.
     Rolloff of registers cannot be described with this model.

     Decimation is NOT included in this user defined function!

     3rd order example:
        _____    _____    _____     _____    _____    _____       ________
       |     |  |     |  |     |   |     |  |     |  |     |     |        |
     ->| INT |->| INT |->| INT |-->| DIF |->| DIF |->| DIF |---->| 1/M**3 |--> (DEC_3)
       |_____|  |_____|  |_____|   |_____|  |_____|  |_____|     |________|

       3 first order integrators   3 first order differentiators   Scaling    Decim by 3

     Debug mode:    DSINC

Documentation in '..\User\entropy.hdr'

       duser function  'entropy(..)' of a binary signal.

       USAGE:   node  <e>  duser  entropy  <bsig>

       Where    <bsig>  is the BINARY signal to analyze (value 0 or 1)
                <e>     is the entropy of the signal

       EXAMPLE:         ...
                        node  x      ...
                        node  y     duser  entropy  x
                        ...
                        terminate   1000000 < LOOP_INDEX

     DEBUG:     no specific directive

Documentation in '..\User\fir.hdr'

     NAPA duser defined functions:  "fir"                                (analog  filter)
     NAPA iuser defined functions:  "fir"                                (digital filter)

           0          1          2                  num-1
              _____      _____               _____
             |     |    |     |             |     |               this header does not
      nx --+-| del  >-+-| del  >-+----- .. -| del  >-+            take profit of the
           | |_____|  | |_____|  |          |_____|  |            possible symmetry of
           |          |          |                   |            the table of tabs as
         __|__      __|__      __|__             ____|____        this is not speeding
        |     |    |     |    |     |           |         |       up the computation.
        |tap 0|    |tap 1|    |tap 2|   ..      |tap num-1|
        |_____|    |_____|    |_____|           |_________|
           |          |           |                   |
           +---------(+)---------(+)--- .. ----------(+)----> ny

     USAGE:

      node <ny> duser  fir  <"fil_nam">  <nx>
      node <ny> iuser  fir  <"fil_nam">  <nx>

      where <nx>        is the node input
            <ny>        is the node output
            <"fil_nam"> is the pathname of the file containing the taps        @ init

     Every line of the taps file must be one of the following types (see also examples)

            n     <hn> ...     // any comment
            # any comment

     Debug mode:    FIR

     Example of input file (digital FIR)

      ## Passband ripple      = +/-2.15 dB
      ## Stopband attenuation =   26.48 dB
      #
      0   3051
      1   5098
      2   7009
      3   9844
      4   10950    // any comment after double slash is allowed.
      5   12043
      6   10950
      7   9844
      8   7009
      9   5098
      10  3051

     example of input file (analog FIR)

      ## Passband ripple      = +/-2.15 dB
      ## Stopband attenuation =   26.48 dB
      #
      0   3051.0
      1   5098.0
      2   7009.0
      3   9844.0
      4   10950.0  // any comment after double slash is allowed.
      5   12043.0
      6   10950.0
      7   9844.0
      8   7009.0
      9   5098.0
      10  3051.0

Documentation in '..\User\firdec.hdr'

     NAPA duser defined functions:   "fir_in", "fir_out"

     USAGE:

       node  <tag>      duser fir_in  <input_node>  "tapfile_name"  <scale_factor>
       decimate ...
       node  <out_node> duser fir_out <tag>

       node  <tag>      duser fir_in  <input_node>  "tapfile_name"
       decimate ...
       node  <out_node> duser fir_out <tag>

       where   <tag>            is a tag used to identify the computed output
               <in_node>        is the input node
               <out_node>       is the output node
               <tapfile_nam>    is the data file pathname                       @ init
               <scale_factor>   is the scale factor                             @ init

     'fir_in' is used to collect double precision input values. A tap file must be given with the fir coefficients included. The
     first value in the tap file is the number of taps (an integer) and the rest of the file are the taps, one value (integer or
     double) per line, starting with the lowest order coefficient.
     A scale factor is given which may be used to scale the filter gain (default 1.0)

     The output of 'fir_in' must be passed to the input of 'fir_out', which calculates the output of the filter. Therefore,
     'fir_out' may be placed on the other side of a decimate statement to save calculations.

     (See also generator 'fir' compiled from 'fir.c' in generic directory 'gen')

     Debug mode:    FIR

Documentation in '..\User\fm.hdr'

     Frequency and/or Phase Modulated Analog Generator and Digital Clock Generator.

     NAPA duser and iuser defined functions:  "fm"

     USAGE:
            node  <nod>  duser  fm  <freq> <phase> (<type>)
            node  <nod>  duser  fm  <freq> <phase>
            node  <nod>  duser  fm  <freq>         (<type>)
            node  <nod>  duser  fm  <freq>

            node  <nod>  iuser  fm  <freq> <phase>
            node  <nod>  iuser  fm  <freq>

     where  <freq>  is the frequency       (may be modulated)
            <phase> is the phase           (may be modulated, default 0.0)
           (<type>) is (sinewave), (cosinewave) or (rectangular) qualifier.            Default: (rectangular)

     Amplitude of the analog generator is [-1.0, +1.0]
     Output of the digital generator is   0  or 1

     PLEASE NOTE that the NAPA nodes "square" and "triangle" are not suited for Frequency Modulation
     as they create phase discontinuities.

     the types (sinewave) and (cosinewave) of this function behave exactly as the NAPA nodes "sine" and "cosine".

     Debug mode:    no specific directive

Documentation in '..\User\geometric.hdr'

     NAPA duser defined function:   "geometric_average"

     Moving Geometric Average (analog).

          0        1        2          num-1
             ___      ___         ___
            |   |    |   |       |   |
     in --+-|del >-+-|del >-+-..-|del >-+
          | |___|  | |___|  |    |___|  |
          |        |        |           |    ______________    __________________
          |        |        |           |   |              |  |                  |
          +-------(x)------(x)---------(x)--| root(x, 1/n) |--| 1 / scale_factor |--> out
                                            |______________|  |__________________|

     Software implementation of the delay chain: a rolling table
               _____________
              |             |
            0 |             |
              |_____________|  new_data    = in
              |             |  running_sum = running_sum - oldest_data + new_data
            1 |             |
              |_____________|  geometric_average = root(running_sum, 1/num) / scale_factor
              |             |
              :             :
              |_____________|
              |             |
          c-1 | newest_data |          :
              |_____________|          :
              |             |
            c | oldest_data |<--- rolling_index ---.
              |_____________|                       \
              |             |          :             \
              :             :         \ /             \
              |_____________|          .               \
              |             |                           \
        num-1 |             |                            \____ in
              |_____________|

     USAGE:

       node <output_node>  duser geometric_average <input_node>  <num>  <scale_factor>
       node <output_node>  duser geometric_average <input_node>  <num>

       where  <input_node>    is the  input node of the moving geometric average filter
              <output_node>   is the output node of the moving geometric average filter
              <num>           is the number of data to geometric_average        @ init
              <scale_factor>  is an optional scale factor  (default 1.0)        @ init

              <input_node>    must be positive or 0

     Debug mode:    no specific directive

Documentation in '..\User\harmonic.hdr'

     NAPA duser defined function:   "harmonic_average"

     Moving Harmonic Average (analog).

                0        1        2          num-1
           ___     ___      ___         ___
          |   |   |   |    |   |       |   |
     in --|1/x|-+-|del >-+-|del >-+-..-|del >-+
          |___| | |___|  | |___|  |    |___|  |
                |        |        |           |   ___   __________________________
                |        |        |           |  |   | |                          |
                +-------(+)------(+)---------(+)-|1/x|-| 1 / (num * scale_factor) |--> out
                                                 |___| |__________________________|

     Software implementation of the delay chain: a rolling table
               _____________
              |             |
            0 |             |
              |_____________|  new_data    = 1.0 / in
              |             |  running_sum = running_sum - oldest_data + new_data
            1 |             |
              |_____________|  harmonic_average = (1.0/running_sum) / (num * scale_factor)
              |             |
              :             :
              |_____________|
              |             |
          c-1 | newest_data |          :
              |_____________|          :
              |             |
            c | oldest_data |<--- rolling_index ---.
              |_____________|                       \
              |             |          :             \
              :             :         \ /             \
              |_____________|          .               \
              |             |                           \
        num-1 |             |                            \____ in
              |_____________|

     USAGE:

       node <output_node>  duser harmonic_average <input_node>  <num>  <scale_factor>
       node <output_node>  duser harmonic_average <input_node>  <num>

       where  <input_node>    is the  input node of the moving harmonic average filter, must be strictly positive.
              <output_node>   is the output node of the moving harmonic average filter
              <num>           is the number of data to average                  @ init
              <scale_factor>  is an optional scale factor  (default 1.0)        @ init

     Debug mode:    no specific directive

Documentation in '..\User\ifft.hdr'

     NAPA duser defined function:  "ifft"

     USAGE:

      node <ny> duser  ifft  <"fil_nam">

      where <ny>        is the node output
            <"fil_nam"> is the pathname of the file containing the spectrum    @ init

     Every line of the data file must be one of the following types:

            <freq>    <realpart0>    <imaginarypart1>       // any comment
            # any comment

     'ON_READ_EOF' is true at the end of the data produced by ifft.
     This macro may be used to control the simulation, e.g. in instruction 'terminate':

         header <napa.hdr>
         ..
         node x duser  ifft  "foo.dat"
         ..
         terminate  ON_READ_EOF_FLAG

     A warning is issued at the end of the simulation if a read overflow occurs somewhere in the simulation.

     See also 'pwl.hdr' for similar functions.

     Debug mode:    IFFT

     Directive:     VERBOSE        (to augment debug information)

Documentation in '..\User\ilt.hdr'

      INVERSE LAPLACE TRANSFORM

      The transfer function of any linear network built from lumped elements such as resistors, inductors, capacitors and
      amplifiers is given by a polynomial fraction in the Laplace domain:

                 ___________
                |           |
                | module    |
      in  ------| described  >------- out
                | by H(s)   |
                |___________|

             N0 + N1*s + N2*s^2 .. + Nn*s^n
      H(s) = ------------------------------       with n <= m
             D0 + D1*s + D2*s^2 .. + Dm*s^m

             where parameters (N0 .. Nn) and (D0 .. Dm) are constant real numbers.

      LIMITATIONS: order of numerator must be smaller or equal to order of denominator.
                   order <= 10

      Based on such a description, this user defined function computes the response in the time domain of the network at each
      period of computation ( 1/FSL ).

      We suppose that the input is sampled at FSL = 1/T. The response of the linear network described by its transfer function is
      therefore the addition of step responses:

      in  = a, b, c, d, e, f, ...
      out = A, B, C, D, E, F, ...

            >.       .<  time_step
             :       :
      in     :       :       :       :       :       :      :
             :       :       :       :       :_______f      :
             :       :_______c       :       |       |      :
            _a       |       |       :       |       |_     :
             |_______:       |       :_______e       :      :
             :       b       |_______|       :       :      :
             :       :       :       d       :       :      :
             :       :       :       :       :       :      :
             :       :       :       :       :       :      :
             :               :       :       :       :      :
      out    :       *       :               :       :      :
             :       A               *       :       :      :
             :       :       *       C               :
             :       :       B       :       *              *
             :       :       :       :       D       *      F
             :       :       :       :       :       E      :

      For multiple inputs, use the superposition theorem:

             .........................................
             .  ______________                       .
             . |              |                      .
             . | H1(s)        |    out1              .
      in1 -----| in1 -> out    >--------+            .
             . | with in2 = 0 |         |    _____   .
             . |______________|         +---|     |  .
             .  ______________              | sum  >----> out
             . |              |         +---|_____|  .
             . | H2(s)        |    out2 |            .
      in2 -----| in2 -> out    >--------+            .
             . | with in1 = 0 |                      .
             . |______________|              == H(s) .
             .........................................   example for voltage inputs

      USAGE:

      node <out_node>  duser  ilt  <array_id>  <in_node>
      node <out_node>  duser  ilt  <array_id>  <in_node>      (<opt>)

      Where:

         <out_node>   is the output node
         <array_id>   is the array of numerator and denominator coefficients                                          @init
         <in_node>    is the input node
         (<opt>)      (print) or (noprint)  to trigger the print of poles and zeroes ot the transfer function         @init
                      (resolution::<num>),                                                                            @init
                      <num>  is the number of intermediate steps to produce one output (an internal repetition of 'ilt' call)

      Coefficients -must- be sorted from lower to higher exponents of s.
      The effective order of numerator cannot be larger than order of denominator,
      but the number of coefficients for the numerator and denominator must be equal:

             ganging <array_id>[]   <num_0> .. <num_n>  <den_0> .. <den_n>       (ganging by position only !)
             where <num_i>.. and <den_i>.. are defined as 'dvar'

      Example: LPF described by its transfer function, a polynomial in the Laplace domain:

           FSL     ______      FSL
         ____/ ___|      |___/ ____
                  |______|                                   3.94781e7
               in          out              H(s) = -----------------------------------
                                                   3.94781e7 + 10882.8 * s + 1.0 * s^2
       ..

       dvar n0   3.94781e7                               // Numerator,   3 coefficients, effective order 0
       dvar n1   0.0
       dvar n2   0.0

       dvar d0   3.94781e7                               // Denominator, 3 coefficients, effective order 2
       dvar d1   10882.8
       dvar d2   1.0

       ganging  num[3]   n0..2                           // Same length for the
       ganging  den[3]   d0..2                           // numerator and the denominator
       ganging  coef[2]  num den                         // Assembling arrays for the ilt user function

       node out duser ilt coef in (print)                // Print the transfer function in s and the poles and zeroes
       ..

       BE CAREFUL to respect the indices: from 0 to max, and NOT from max to 0!!!

     Debug mode:    ILT

Documentation in '..\User\intreal.hdr'

     NAPA duser defined function:  "intreal".

     Model of SWC NON INVERTING DELAYED INTEGRATOR. Based on an EXACT analytical solution, with a transconductance single stage
     opamp having some DC offset, limited DC gain, limited bandwidth (one pole approximation) and limited symmetrical slew-rate.

     One pole approximation is valid for 'one-stage' transconductance opamp with good phase and gain margins.

     Model describes a SINGLE-ENDED architecture but is intended to be used to simulate a differential architecture. Parameters
     mapping from differential to single-ended is therefore necessary.

     Phase transitions are supposed to be infinitely short.

     Charge injection is supposed to be negligible thanks to appropriate clocking. Clock feedthrough is supposed to be negligible
     thanks to symmetrical clocks and switches.

     Voltage clipping is not modelled. Opamp is linear (but with slew rate limitation).

     Switches are supposed to have a negligible ON and infinite OFF resistance.

     Output is sampled by the device connected at output during phase PHI1 (see below).

     >>>>>>>>  The short form '&delay' is MANDATORY here to introduce the inherent delay of the circuit!!!

     This header is therefore intended to be used through dedicated cells (e.g. intdr1.net, ..).

     See usage of this duser function in cells 'intdr1.net', .. 'intdr3.net' in directory '/Simulate/Napados/Net/Integrator1'

                ___________
               |           |
      vi ------|            >--- out
               |  duser    |
      vj ------|           |
               |  intreal  |
      vk ------|           |
               |___________|
                        &delayed

      USAGE:   integrator with 1, 2 or 3 inputs  (see figure below).

      'realistic' integrator  (gain, bandwidth and slew-rate limited)

      node vo  duser intreal  vi        ci        cs  cswl  gm gds imax  off  ca co    &delayed
      node vo  duser intreal  vi vj     ci cj     cs  cswl  gm gds imax  off  ca co    &delayed
      node vo  duser intreal  vi vj vk  ci cj ck  cs  cswl  gm gds imax  off  ca co    &delayed

      'ideal' integrator      (all characteristics are ideal, but offset).

      node vo  duser intreal  vi        ci        cs        &delayed
      node vo  duser intreal  vi        ci        cs  off   &delayed
      node vo  duser intreal  vi vj     ci cj     cs        &delayed
      node vo  duser intreal  vi vj     ci cj     cs  off   &delayed
      node vo  duser intreal  vi vj vk  ci cj ck  cs        &delayed
      node vo  duser intreal  vi vj vk  ci cj ck  cs  off   &delayed

      (any integrator having 'gm', 'gds' AND 'imax' at 0.0 is also considered as ideal)

      Model of the transconductance amplifier:

            ...............
            :             :
            : ca  |\      :           Idealized transconductance opamp
     va ----:-----a  \    :           with offset, limited gain, limited
            :     |   o>--:-- vo      bandwidth and limited slew-rate.
         +--:-----b  /    :
        _|_ :     |/   co :           off                               @ init
            :          gm :           ca                                @ init
            :         gds :           co                                @ init
            : off    imax :           gm                                @ init
            :.............:           gds                               @ init
                                      imax                              @ init

          ..................................................
          :                                                :
        -----off----+                 +------+--------+-------
          :         |                _|_    _|_       |    :
          :     ca  |               |   |  |   |  co  |    :
       va :       =====  vs  ---->  | is|  |gds|    =====  : vo
          :         |               |___|  |___|      |    :
          :         |                 |      |        |    :     where  is = MIN(imax, gm*vs)
        ------------+-----------------+------+--------+-------
          :................................................:

      These parameters determine the gain, bandwidth and slewrate of the opamp. The load is depending on the devices connected
      to the opamp. In this application the load is capacitive ('ceq') and is different during clock phases PHI1 and PHI2.

        Av:   gm / gds
        Wt:   SQRT(gm*gm - gds*gds) / ceq
        SR:   Imax / ceq

      Inverting Switched Capacitor Integrator Model using the Transconductance Amplifier:

                                                    cs
                                                       ||
                                           +-----------||------+
                                           |           ||      |
                                           |                   |
                                           |  ...............  |    OUTPUT
                    ci                     |  :             :  |     /
                      ||              va   |  : ca  |\      :  |    /
      vi --PHI1---+---||----+---PHI2---+---+--:-----a  \    :  |  vo
                  |   ||    |          |      :     |   o>--:--+-------PHI1----+-----+
                  |         |          |   +--:-----b  /    :                  |     |
                 PHI2      PHI1        |   |  :     |/   co :                =====  PHI2
                  |         |          |   |  :          gm :            cswl  |     |
                 _|_       _|_         |  _|_ :         gds :                 _|_   _|_
                                       |      : off    imax :
                                       |      :.............:
                    cj                 |
                      ||               |       <---------------> 1.0/FSL
      vj --PHI1---+---||----+---PHI2---+      _:         ______:         ______
                  |   ||    |          |       \________/ PHI1 \________/ PHI1 \__
                  |         |          |         ______          ______          _
                 PHI2      PHI1        |      __/ PHI2 \________/ PHI2 \________/
                  |         |          |
                 _|_       _|_         |
                                       |      Sampling    during phase  PHI1.
                                       |      Integration during phase  PHI2.
                    ck                 |
                      ||               |
      vk --PHI1---+---||----+---PHI2---+
                  |   ||    |                 Model considers that input and output signals are sampled at the end of PHI1.
                 PHI2      PHI1
                  |         |
                 _|_       _|_

        ci:   input capacitor i of the integrator                               @ init
        cj:   input capacitor j of the integrator                               @ init
        ck:   input capacitor k of the integrator                               @ init
        cs:   integration capacitor of the integrator                           @ init
        cswl: switched output capacitance                                       @ init

           integration    sampling
         <-------------------------> 1.0/FSL
         :                         :
        _:              ___________:              ___________
         \_____________/ PHI1      \_____________/ PHI1      \__
           ___________               ___________               _
        __/ PHI2      \_____________/ PHI2      \_____________/

     directive INTREAL_DUTYCYCLE        (default 0.50)    clock duty cycle: (duration of PHI1)/PERIOD

     *****************************************************************************************************************************

     NOTE on capacitors:

       Do not forget that each capacitor has a parasitic. It is left to the user to place the most important parasitic capacitance
       on the appropriate node of the capacitor (generally on the low impedance side).

                 C ||
       LO ---------||----+--------- HI
                   ||    :
                         :
                        === C/FOM       FOM: Factor of Merit  (Analog process 10 .. 20)
                         :
                        _:_

     directive CAPACITOR_FOM           (default 10.0)

     *****************************************************************************************************************************

     NOTE on the model:

        It is VERY important to evaluate ca, co, cswl accurately.

        A typical ca load:

          The input capacitance of the opamp. Miller effect may exist on input!!! This effect is NOT modelled here.

        A typical co load:    capacitances and parasitic capacitances.

              cs
                 ||
          +------||-----+--------+
          |      ||     :        |
          |            ===       |               co = cs/FOM + copamp + cload1   (this load is permanent)
          |             : cs/FOM |
          |  |\        _:_       |
       ---+--|  \                |    vo
             |    >-+------------+--+--- - - -
             |  /   :               |
          +--|/    === copamp     =====  cload1
          |         :               |
         _|_       _:_             _|_

        A typical cswl load:   e.g. a similar stage driven by the integrator:

                                                                             ||
                                                                       +-----||-----+
                                                        cload2         |     ||     |
                                                      ||               |  |\        |
                        vo - - - --PHI1--+-----+------||------+--PHI2--+--|  \      |
                                         |     :      ||      |           |    >----+
                                         |     :              |           |  /
                                        PHI2  ===            PHI1      +--|/
                                         |     : cload2/FOM   |        |
                                        _|_   _:_            _|_      _|_

        In the model, this capacitance cswl is approximated by:

                                                        cload2
                                                      ||
                        vo - - - --PHI1--+-----+------||------+
                                         |     :      ||      |
                                         |     :              |
                                        PHI2  ===             |  cswl = cload2 + cload2/FOM   (this load is switched)
                                         |     : cload2/FOM   |
                                        _|_   _:_            _|_

     *****************************************************************************************************************************

     **** HELP TO USER ****

        To get an internal view of the behavior of the integrator, it is possible to use the directives here below
        (take care to limit the simulation length!):

        (This feature is not available for ideal opamp)

      directive INTREAL_VIEWFILE

        Time domain output of internal viewer is then directed in a file <fnam_suff_id.out>
        where <fnam> is the name of the NAPA source file without extension,
        and <suff> is, by default, the suffix "ir" followed by the ID of the user function (0..).

        (this directive is not necessary if the directive INTREAL_VIEWCOND is defined)

        The default suffix of the internal viewer file may be changed:

      directive INTREAL_SUFFIX     "a_new_suffix"

        The output rate is 2*INTREAL_VIEWRATE the ordinary output rate, i.e. for each period corresponding to the local sampling
        frequency, 2*INTREAL_VIEWRATE data are output in this file.

      directive INTREAL_VIEWRATE   <a_positive_integer_number>          (default 500)

        The directive below limits the output of the internal viewer. Output is triggered by the boolean expression:

      directive INTREAL_VIEWCOND   <a_C_expression_returning a boolean>

      **** EXAMPLE ****

        directive INTREAL_VIEWFILE
        directive INTREAL_VIEWCOND   (TIME > 10.0e-6) && (TIME < 20.0e-6)

        for a NAPA file  'foo.nap', the output name for placement id=3 is  'foo_ir_3.out'
        the output will be triggered between simulation time 10 and 20 us.

     Debug mode:    INTREAL

     Directive:     VERBOSE        (to augment debug information)
                    and the directives described above.

Documentation in '..\User\isinc.hdr'

     NAPA iuser defined functions:  "sinc_a"  "sinc_b"

             _______        :          _______
        in  |       |  ab   :         |       |   out
        ----| SIN_A |-------:---------| SIN_B |-----
            |_______|       :         |_______|
                        ->decim->
     USAGE:

            node <ab_node>  iuser sinc_a <sinc_order> <in_node>
            ...
            decimate <decimation_number>
            ...
            node <out_node> iuser sinc_b <sinc_order> <ab_node>

       where  <sinc_order>     is the order of the sinc                         @ init
              <in_node>        is the  input node of the filter
              <out_node>       is the output node of the filter
              <ab_node>        is the intermediate node

     These functions must be used in combination to build a SINC filter. See file "sinc.net" in "net" directory.

     Debug mode:    no specific directive

Documentation in '..\User\lfsr.hdr'

     NAPA iuser defined function:  "lfsr"

     Pseudo Random Noise Generator based on Linear Feedback Shift Register implemented as
        a Fibonacci LFSR

        node <nod> iuser  lfsr  <n>    (fibonacci)

        where:  <nod>  is the 1 bit output node
                <n>    is the order of the shift register  (between 2 and 512)   with a period of (2^n)-1         @ init
                Default option is (fibonacci)

           +----------------+--------> out
           |                |
      _____|_____        ___v___
     |           |      |       |
     |   XNOR    |      | Delay |
     |_ ___ ___ _|      |___ ___|
       |   |   |            |       tap 1
      ... ... ...          ...
       |   |   |            |
       |   |   |         ___v___
       |   |   |        |       |
       |   |   |        | Delay |
       |   |   |        |_______|                        Fibonacci LFSR
       |   |   |            |
       |   |   +------------+ bi    tap i
       |   |                |
      ...                  ...
       |                    |
       |                 ___v___
       |                |       |
       |                | Delay |
       |                |_______|
       |                    |
       +--------------------+ bn    tap n

       Simulator implementation of the delay chain: a rolling table

       PLEASE NOTE that  2^512 is a number larger than 1.3 10^154. We may think that it is really a big period.

       directive 'debug LFSR' triggers the output of debug information.

       You may check the periodicity of the sequence with tool 'pdetect' when period is not too long :-)

     Debug mode:    LFSR

Documentation in '..\User\max2max.hdr'

     NAPA duser defined function:   "max2max"
     NAPA iuser defined function:   "max2max"

     Tracking local maximum (analog or digital)

          2        1        0
             ___      ___
            |   |    |   |
     in --+-|del >-+-|del >-+
          | |___|  | |___|  |   ____________________
          |        |        |  |                    |
          |        |        +-->                    |
          |        +-----------> store if local max  >--- out
          +-------------------->                    |
                               |____________________|

     USAGE:

       node <output_node>  duser max2max <input_node>
       node <output_node>  iuser max2max <input_node>

       where  <input_node>    is the  input node
              <output_node>   is the output node

     Debug mode:    no specific directive

Documentation in '..\User\median.hdr'

     NAPA duser and iuser defined functions:   "median"

     Rectangular Median Filter  (NON LINEAR FILTERING!)

     USAGE:

       node  <output_node>  duser  median   <input_node>   <length>
       node  <output_node>  iuser  median   <input_node>   <length>

       where <length>  is the length of the filter                              @ init
              must be a positive integer of the form (2*k)+1

                _____       _____           _____
               |     |     |     |         |     |
       in --+--| del  >-+--| del  >-+- .. -| del  >-+
            |  |_____|  |  |_____|  |      |_____|  |
            |0          |1          |2 ..           |2k
       _____V___________V___________V_______________V_____
      |                                                   |
      |   Sort by value, (k)th value is then the median   |--> out
      |___________________________________________________|

     Software implementation of the delay chain: a rolling table
               _____________
              |             |
            0 |             |
              |_____________|
              |             |
            1 |             |
              |_____________|
              |             |
              :             :
              |_____________|
              |             |
          c-1 | newest_data |          :
              |_____________|          :
              |             |
            c | oldest_data |<--- rolling_index ---.
              |_____________|                       \
              |             |          :             \
              :             :          :              \
              |_____________|         \ /              \
              |             |          .                \
        num-1 |             |                            \____ in
              |_____________|

     Debug mode:    no specific directive

Documentation in '..\User\min2min.hdr'

     NAPA duser defined function:   "min2min"
     NAPA iuser defined function:   "min2min"

     Tracking local minimum (analog or digital)

          2        1        0
             ___      ___
            |   |    |   |
     in --+-|del >-+-|del >-+
          | |___|  | |___|  |   ____________________
          |        |        |  |                    |
          |        |        +-->                    |
          |        +-----------> store if local min  >--- out
          +-------------------->                    |
                               |____________________|

     USAGE:

       node <output_node>  duser min2min <input_node>
       node <output_node>  iuser min2min <input_node>

       where  <input_node>    is the  input node
              <output_node>   is the output node

     Debug mode:    no specific directive

Documentation in '..\User\multitone.hdr'

     NAPA duser defined function:  "multitone"

     Self Windowing Periodic Random Noise Generator to be used with 'fairly' linear circuits for multitone test.

     It produces a COHERENT MULTITONE SIGNAL  (a comb of sinewaves).

       Efficiency: this function is very fast as it precomputes and reuses heavily a unique table of sine,
                   which is, by the way, used also by the FFT based functions and by the vast majority of windowing functions!

     USAGE:

       node  <out>  duser  multitone  <offset> <amplmax>                 <numpnt>  (<opt>)
       node  <out>  duser  multitone  <offset> <amplmax>  <bandwidth>    <numpnt>  (<opt>)
       node  <out>  duser  multitone  <offset> <amplmax>  <fmin> <fmax>  <numpnt>  (<opt>)

       <amplmax>     is the max amplitude of the sinewave (excluding offset)    @ init
       <offset>      DC offset of the sum of sinewaves                          @ init
       <fmin> <fmax> frequency of sinewaves in [fmin.. fmax]                    @ init
       <bandwidth>   frequency of sinewaves in [0.. bandwidth], default FSL/2   @ init
       <numpnt>      is the number of points to be coherenty sampled            @ init

       (<opt>)   (linscale) or (logscale)          default scale is (linscale)  (optional)
                 (random)   or (equal)             default phase is (random)    (optional)

       According to these options, the waveform will be made as a sum of coherent sinewaves quasi-linearly or logarithmically
       spaced in frequency domain from <fmin> to <fmax> with their phases randomly chosen or equally spaced.

       Amplitude of resulting signal is never larger than (<offset> + <amplmax>) and never smaller than (<offset> - <amplmax>)
       by construction.

       directive MULTITONE_NUM sets the MAX number of sinewaves building the signal. Default is 100.

     CAUTION:      USE LOCAL SAMPLING FREQUENCY FSL !
                   PLACE THIS FUNCTION IN THE APPROPRIATE NAPA SEGMENT.

     Debug mode:   MULTITONE   COHERENT

     Directive:    VERBOSE        (to augment debug information)

Documentation in '..\User\pink.hdr'

     Generate a 'good' approximation of Pink Noise (1/f noise + normal noise) using the Gardner method (Voss McCartney Algorithm).

     USAGE:

       node <out>  duser pink  <dc_offset> <wfactor> <pfactor>

       where  <out>            is the output node
              <dc_offset>      average value
              <wfactor>        white noise density of floor    (Rms/Hz^0.5)               @ init
              <pfactor>        1/f noise density               (Rms/decade^0.5)           @ init

     Characteristic of white noise is that the power density all over bandwidth is constant.
     Characteristic of 1/f noise is that the power/decade is constant.

              ________________________________________
             |                                        |
             |   ___________     ____________         |
             |  |           |   |            |        |
             |  | 1/f noise  >--|  x pfactor  >--(+)--|-----> out
             |  |___________|   |____________|    |   |
             |   ___________     ____________     |   |
             |  |           |   |            |    |   |
             |  |White noise >--|  x wfactor  >--(+)  |
             |  |___________|   |____________|    |   |
             |                   ____________     |   |
             |                  |            |    |   |
             |                  |  DC offset  >---+   |
             |                  |____________|        |
             |                                        |
             |__________________________________PINK__|

     Debug mode:    PINK

Documentation in '..\User\PLA.hdr'

      NAPA iuser defined function:  "PLA"    Model dedicated to the description of small Programmable Logic Array.

      USAGE:                             most significant ... less significant bit

      node <out> iuser  PLA <descriptor>  <b0>                                      number of elements of the descriptor: n =   2
      node <out> iuser  PLA <descriptor>  <b1> <b0>                                 number of elements of the descriptor: n =   4
      node <out> iuser  PLA <descriptor>  <b2> <b1> <b0>                            number of elements of the descriptor: n =   8
      node <out> iuser  PLA <descriptor>  <b3> <b2> <b1> <b0>                       number of elements of the descriptor: n =  16
      node <out> iuser  PLA <descriptor>  <b4> <b3> <b2> <b1> <b0>                  number of elements of the descriptor: n =  32
      node <out> iuser  PLA <descriptor>  <b5> <b4> <b3> <b2> <b1> <b0>             number of elements of the descriptor: n =  64
      node <out> iuser  PLA <descriptor>  <b6> <b5> <b4> <b3> <b2> <b1> <b0>        number of elements of the descriptor: n = 128
      node <out> iuser  PLA <descriptor>  <b7> <b6> <b5> <b4> <b3> <b2> <b1> <b0>   number of elements of the descriptor: n = 256

      where <descriptor> is a n bits PLA descriptor '(size 2^n) defined by a NAPA instruction 'ganging'       (init)
      where <bi>         is the ith bit of the input

      EXAMPLE:
                  node out  iuser  PLA  mytable  b2 b1 b0    //   n   = 3
                  ganging   mytable[8]    0 1 1 0 1 0 1 0    // 2^n   = 8

                                          ^ ^ ^ ^ ^ ^ ^ ^
      the corresponding truth table:      : : : : : : : :
                                          : : : : : : : :
               (b2,b1,b0) ->  out         : : : : : : : :
                                          : : : : : : : :
       '0'  =  ( 0, 0, 0) ->   0   -------+ : : : : : : :
       '1'  =  ( 0, 0, 1) ->   1   ---------+ : : : : : :
       '2'  =  ( 0, 1, 0) ->   0   -----------+ : : : : :
       '3'  =  ( 0, 1, 1) ->   1   -------------+ : : : :
       '4'  =  ( 1, 0, 0) ->   0   ---------------+ : : :
       '5'  =  ( 1, 0, 1) ->   1   -----------------+ : :
       '6'  =  ( 1, 1, 0) ->   1   -------------------+ :
       '7'  =  ( 1, 1, 1) ->   0   ---------------------+

Documentation in '..\User\pulse.hdr'

     NAPA duser defined function:   "pulse"

     Periodic pulses with sigmoid, trapezoid, sinusoid shapes
     Output range is normalised to [-1, 1]

     USAGE:

       node <out_node> duser pulse  <period> <delay> <ton> <toff>  <tr> <tf>
       node <out_node> duser pulse  <period> <delay> <ton> <toff>  <tr> <tf> (exponential)
       node <out_node> duser pulse  <period> <delay> <ton> <toff>  <tr> <tf> (sigmoid)
       node <out_node> duser pulse  <period> <delay> <ton> <toff>  <tr> <tf> (sinusoid)
       node <out_node> duser pulse  <period> <delay> <ton> <toff>  <tr> <tf> (trapezoid)

       where  <period>      is the period of the pulse                          @ init
              <delay>       is the delay of the pulse                           @ init
              <ton> <toff>  positions of zero crossing                          @ init
              <tr>  <tf>    is the rise and fall transition time of the pulse   @ init

              Option default is (trapezoid)

       These times are defined as the position of the tangents:

                        ton, toff  positions of zero crossing in time domain
                        tr, tf     transitions of tangent in 0.0 extended from -1.0 to 1.0

       when  toff >> ton :
                          _____________________
       +1                /:                   :\
                        / :                   : \                           /
                       /  :                   :  \                         /
                <-----/--->  tr            tf <---\----->                 /
        0  .....:..../.............................\....:................/...
                :   /:                             :\   :               /:
                :  / :                             : \  :              / :
                : /  :   tangents to the waveform  :  \ :             /  :
       -1  _____:/   :                             :   \:____________/   :
                :    ton                          toff                   :
                :                                                        :
                :    :                                                   :
                :    :                                                   :
       delay --->    <------------------- period ------------------------>

       when  toff << ton :
           ______                                       _____________
       +1       :\                                     /:            \
                : \      tangents to the waveform     / :             \
                :  \                                 /  :              \
                <---\----->  tf            tr <-----/--->               \
        0  ..........\....:...................:..../.....................\...
                :    :\   :                   :   /:                     :\
                :    : \  :                   :  / :                     : \
                :    :  \ :                   : /  :                     :  \
       -1       :    :   \:___________________:/   :                     :
                :   toff                          ton                    :
                :                                                        :
                :    :                                                   :
                :    :                                                   :
       delay --->    <------------------- period ------------------------>

     Debug mode:    PULSE

     Directive:     VERBOSE        (to augment debug information)

Documentation in '..\User\pwl.hdr'

     NAPA duser defined functions:  "pwl"             (analog  piece wise linear waveform)
     NAPA iuser defined functions:  "pwl"             (digital piece wise staircase waveform)

     A first order interpolation is used between points for the duser flavor of this function ONLY.

     It could be also used to describe a tabulated function x -> y, or as a piece-wise description of an input depending on time.
     See also "read1.hdr" and "waveform.hdr".

     USAGE:

      node <ny> duser  pwl  <"fil_nam">  <nx>
      node <ny> duser  pwl  <"fil_nam">  <nx>         (<opt>)
      node <ny> duser  pwl  <"fil_nam">  <nx> <col>
      node <ny> duser  pwl  <"fil_nam">  <nx> <col>   (<opt>)

      node <ny> iuser  pwl  <"fil_nam">  <nx>
      node <ny> iuser  pwl  <"fil_nam">  <nx>         (<opt>)
      node <ny> iuser  pwl  <"fil_nam">  <nx> <col>
      node <ny> iuser  pwl  <"fil_nam">  <nx> <col>   (<opt>)

      where <ny>        is the node output
            <"fil_nam"> is the pathname of the file containing the waveform                                             @ init
            <nx>        is the input (TIME, node, variable, ...)
            <col>       0 being the column number of the 'X' input values,
                        <col> must be a number 1...  and is the column number of 'Y' data    default = 1                @ init
           (<opt>)      (periodic)  or (aperiodic)                                           default is (aperiodic)
                        (symmetric) or (asymmetric)                                          default is (assymetric)

     Every line of the data file must be one of the following types:
            <x>      <y1>     ...      // any comment
            # any comment

     It should be understood as piece-wise description of functions: y1= f1(x), y2= f2(x) ..

     In a periodic pwl, the first and the last x values must be the same.
     In a symmetric pwl, the RIGHT hand side of the pwl must be described, starting by the (x,y) values of the symmetry axis.
     By construction, a symmetric description is of course automatically compatible with the use of the (periodic) option.

     Please note that the 'X' values must be strictly monotonic.

     Example:
              #  X      Y
               5.0   4.50              //   <---- it will be the axis of symmetry for option (symmetric)
               7.0   2.00
              # comment
               9.0   1.00
              15.0   0.01

      without symmetry                                            (5.0, 4.50), (8.0, 2.00), (10.0, 1.00), (15.0, 0.01)
      with    symmetry (-10.0, 0.01), (-5.0, 1.00), (-3.0, 2.00), (5.0, 4.50), (8.0, 2.00), (10.0, 1.00), (15.0, 0.01)

     Same input file may contain advantageously several columns of data shared by several user functions.

     Example:

              #*     X    Y1    Y2    Y3
                0.0      0.0   0.0   0.0
                0.1e-6   1.0   1.0   1.0
              100.0e-6   1.0   1.0   1.0
              110.1e-6   0.0   0.0   0.0
              200.1e-6   0.0   0.0   1.0

     It is possible to replace a number by ?, the entry will then be ignored

     Example: These 3 files

        :         file1                  :         file2                  :         file3                  :

        :         #*     X    Y1         :         #*     X    Y2         :         #*     X    Y3         :
        :           0.0      0.0         :           0.0      0.0         :           0.0      0.0         :
        :           0.1e-6   1.0         :          50.0e-6   1.0         :         100.0e-6   1.0         :
        :         125.0e-6   1.0         :         125.0e-6   1.0         :         125.0e-6   1.0         :
        :         125.1e-6   0.0         :         175.0e-6   0.0         :         225.0e-6   0.0         :
        :                                :         250.0e-6   0.0         :                                :
        :                                :         300.0e-6   1.0         :                                :

     can be combined in a single one, taking advantage of the symbol ?

        :         file123                            :

        :         #*     X    Y1    Y2    Y3         :
        :           0.0      0.0   0.0   0.0         :
        :           0.1e-6   1.0     ?     ?         :
        :          50.0e-6     ?   1.0     ?         :
        :         100.0e-6     ?     ?   1.0         :
        :         125.0e-6   1.0   1.0   1.0         :
        :         125.1e-6   0.0     ?     ?         :
        :         175.0e-6     ?   0.0     ?         :
        :         225.0e-6     ?     ?   0.0         :
        :         250.0e-6     ?   0.0     ?         :
        :         300.0e-6     ?   1.0     ?         :

     This header will be used advantageously inside a CELL     >>>   see files  <PWL/d.net> or <PWL/i.net>

     ANALOG waveform generator uses a FIRST ORDER INTERPOLATION between specified points.
     DIGITAL waveform generator is building classical digital STAIRCASE waveforms.

     Please note that user's digital and analog functions can share the same input file.

     Debug mode:    PWL
     Directive:     VERBOSE        (to augment debug information)

Documentation in '..\User\read1.hdr'

     NAPA duser defined functions:  "read"                             (analog  waveform)
     NAPA iuser defined functions:  "read"                             (digital waveform)

     This is the simplest way to create a signal from raw data contained in a text file.
     One line = One output at local sampling rate 'FSL'. No data interpolation!
     See also files 'read2.hdr', 'pwl.hdr' and 'wavefile.hdr'.

     USAGE:

      node <ny> duser  read  <"fil_nam">         (<option>)
      node <ny> duser  read  <"fil_nam">  <col>  (<option>)

      node <ny> iuser  read  <"fil_nam">         (<option>)
      node <ny> iuser  read  <"fil_nam">  <col>  (<option>)

      where <ny>         is the node output
            <"fil_nam">  is the pathname of the file containing the waveform                                 @ init
            <col>        is the column number of the 'Y' data                    default is 0                @ init
            (<option>)   Optional qualifier:   (periodic), (aperiodic)           default is (aperiodic)      @ init

      *** ADVANCED USERS:    It is possible to preprocess the file by any executable like a script written in 'perl', "DOS", ...
      ***                    the user function must then be called with option (script)
      ***                    and the script is defined with 'directive READ_SCRIPT_COMMAND "..."
      ***
      ***
      ***    node <ny> duser  read  <"fil_nam">         (<option>)   (script)
      ***    node <ny> duser  read  <"fil_nam">  <col>  (<option>)   (script)
      ***
      ***    node <ny> iuser  read  <"fil_nam">         (<option>)   (script)
      ***    node <ny> iuser  read  <"fil_nam">  <col>  (<option>)   (script)
      ***
      ***              Scripts should accept the file <"fil_nam"> as only input parameter and their output must -of course- obey
      ***              to file format described below.
      ***
      ***              The output of the script is stored in an intermediate file called "PREFIX_filnam" where PREFIX is defined
      ***              by another directive 'directive READ_SCRIPT_PREFIX "xxxxxx". Default value is "temp_".

     Format of input file:
     Every line of the data file must be one of the following types:

            column #0   column #1

            <y0>        <y1> ...      // any comment
            # any comment

     PLEASE NOTE that non alphanumeric characters are ignored, thus commas for instance are accepted:

            column #0   column #1

            <y0>,       <y1> ...     // any comment
            # any comment

     Hexadecimals must be coded with prefix 0X, octal with prefix 0.

     FIRST AND LAST 'Y' VALUES OF A PERIODIC SIGNAL MUST BE EQUAL! NO DATA INTERPOLATION!

     Same input file may contain advantageously several columns of data shared by several user functions.

     Please note that user's digital and analog functions can share the same input file.

     'ON_READ_EOF_FLAG' is true at the end of the file being read (aperiodic only).
     This macro may be used to control the simulation, e.g. in instruction 'terminate':

         header <napa.hdr>
         ..
         node x duser  read  "foo.dat"  0  (aperiodic)
         ..
         terminate ON_READ_EOF_FLAG

     A warning is issued at the end of the simulation if a read overflow occurs somewhere in the simulation. Only valid for
     'aperiodic' option (see '../Resource/read.hdr')

     Debug mode:    READ

     Directives:    VERBOSE                 (to augment debug information)
                    READ_SCRIPT_COMMAND     (mandatory when option (script) is chosen)
                    READ_SCRIPT_PREFIX      (optional when option (script) is chosen)

                    READ_NSKIP <n>          allows to skip <n> lines for format mismatches, default is 1.

Documentation in '..\User\read2.hdr'

     NAPA duser defined functions:  "read2"                            (analog  waveform)
     NAPA iuser defined functions:  "read2"                            (digital waveform)

     Reserved to SPECIFIC situations where several files must be concatenated. Prefer the user functions 'read' when possible.

     This is a way to create a signal from raw data contained in a set of text files.
     One line = One output at local sampling rate 'FSL'. No data interpolation!

     Very similar to the user function "read" (See file "read1.hdr"), at the exception of:

      1 -  File or column may be changed anytime in the simulation.
      2 -  No 'periodic' or 'aperiodic' options. 'aperiodic' behavior only is implemented.
      3 -  no interaction with READ_EOF_FLAG.

     USAGE:

        node <ny> duser  read2  <"fil_nam">
        node <ny> duser  read2  <"fil_nam">  <col>

        node <ny> iuser  read2  <"fil_nam">
        node <ny> iuser  read2  <"fil_nam">  <col>

        where <ny>        is the node output
              <"fil_nam"> is the pathname of the file containing the waveform
              <col>       is the column number of the 'Y' data (default = 0)

     File is read at each change of <fil_nam> or <col>.

     Format of input file:

     Every line of the data file must be one of the following types:
            <y0>     <y1> ...     // any comment
            # any comment

     PLEASE NOTE that non alphanumeric characters are ignored, thus commas for instance, are accepted.
     Hexadecimals must be coded with prefix 0X, octal with prefix 0.

     Same input file may contain advantageously several columns of data shared by several user functions.

     NO DATA INTERPOLATION!

     Please note that user's digital and analog functions can share the same input file.

     A warning is issued at the end of the simulation if a read overflow occurs somewhere in the simulation
     (see '../Resource/read.hdr').

     See also 'read1.hdr', pwl.hdr' and 'wavefile.hdr' for similar functions.

     Debug mode:    READ2

     Directive:     VERBOSE             (to augment debug information)
                    READ_NSKIP <n>      allows to skip the <n> first lines for format mismatches, default is 1.

Documentation in '..\User\resonator.hdr'

     Second Order Resonator generating a sine or cosine wave      (NAPA node 'osc' implements this code using long double numbers)

     NAPA duser defined function:  "resonator"

     USAGE:
        node <nod> duser resonator  <offset> <ampl> <freq> <phase>   (<opt>)

        where:   <nod>       is the output node
                 <offset>    is the DC offset
                 <ampl>      is the peak amplitude
                 <freq>      is the frequency                                   @ init
                 <phase>     is the phase                                       @ init
                 <opt>      (sine), (cosine)                                    @ init     default is (sine)

      The resonator is implemented as a 2-pole filter described by the following difference equation:

           x[n] = k * x[n-1] - x[n-2]

      Where k is a constant defined as

           k = 2.0 * cos(2Pi * freq/FSL)

      An initial impulse is required to make the oscillator begin running.
      If x[n-1] and x[n-2] are both zero, every succeeding X[n] will be zero.

      To start the oscillator, set

           x[n-1] = sin(phase)                          for option (sine)
           x[n-2] = sin(phase - (2Pi*freq/FSL))         for option (sine)
           x[n-1] = sin(phase + PI/2)                   for option (cosine)
           x[n-2] = sin(phase + PI/2- (2Pi*freq/FSL))   for option (cosine)

      Amplitude and offset may be varied during simulation

                                 ______     ____
                            x2  |      |   |    |
           +--------------------| * -1  >--|    |
           |                    |______|   |    |  x0
           |                     ______    |sum  >--+
           |                x1  |      |   |    |   |
           |                +---| * k   >--|    |   |
           |                |   |______|   |____|   |
           |    ______      |    ______             |
           |   |      |     |   |      |            |
           +--< delay |--+--+--< delay |------------+
           x2  |______|  |  x1  |______|           x0
                         |   ___
                         +--|   |    ___
                            | x  >--|   |             out
           ampl ------------|___|   | +  >--------------->
           offset ------------------|___|

Documentation in '..\User\rms.hdr'

     NAPA duser defined function:   "rms_average"

     RMS Moving Average (analog).

           0          1              num-1
             _____           _____
            |     |         |     |
     in --+-| del  >-+--.. -| del  >-+
          | |_____|  |      |_____|  |
          |          |               |
          |          |               |
        (sqr)      (sqr)           (sqr)            ____________________________
          |          |               |             |                            |
          +---------(+)-.. ---------(+)---(sqrt)---| 1/(sqrt(num)*scale_factor) |---> out
                                                   |____________________________|

     Software implementation of the delay chain: a rolling table
               __________________
              |                  |
            0 |                  |
              |__________________|
              |                  |  running_sum = running_sum - sqr(oldest_data) + sqr(in)
            1 |                  |
              |__________________|  rms_average = sqrt(running_sum/num) / scale_factor
              |                  |
              :                  :
              |__________________|
              |                  |
          c-1 | sqr(newest_data) |          :
              |__________________|          :
              |                  |
            c | sqr(oldest_data) |<--- rolling_index ---.
              |__________________|                       \
              |                  |          :             \
              :                  :          :              \
              |__________________|         \ /              \
              |                  |          .                \
        num-1 |                  |                            \____ in
              |__________________|

     USAGE:

       node <output_node>  duser rms_average <input_node>  <num>  <scale_factor>
       node <output_node>  duser rms_average <input_node>  <num>

       where  <input_node>   is the  input node of moving RMS average filter
              <output_node>  is the output node of moving RMS average filter
              <num>          is the number of data to average                   @ init
              <scale_factor> is an optional scale factor (default 1.0)          @ init

       <scale_factor> is a real.

     Debug mode:    no specific directive

Documentation in '..\User\sarc.hdr'

      NAPA duser defined function:  "sarc"         'SEMI ANALYTICAL RECURSIVE CONVOLUTION'

      Used to model and simulate 'piecewise linear' circuits in time domain.

      >>> This header is using the 'SARC' engine developped by JACQUES MEQUIN.

      This header is currently supporting circuits from 1 to max 12 inputs, and from 1 to max 64 outputs.

      The duser sarc main function is called to compute the results. Results are stored in an internal array identified by <tag>:

          node  <tag>   duser  sarc   <myfun()>  <parm>  <in1>
          node  <tag>   duser  sarc   <myfun()>  <parm>  <in1> <in2>
          node  <tag>   duser  sarc   <myfun()>  <parm>  <in1> <in2>  ...  <in12>
                  |                      |
                  +-------------------+  |
                                      |  |
      The outputs are obtained by     |  +-------------------------------------------------------------------------------------+
      specific calls of the function: |                                                                                        |
                                      v                                                                                        |
          node  <out1>  duser sarc  <tag>   (<an_output_name_1>)                                                               |
          node  <out2>  duser sarc  <tag>   (<an_output_name_2>)                                                               |
          ...                                                                                                                  |
                                                                                                                               |
     where  <in..>              inputs of the circuit (1 to 12) as specified in the definition of function 'myfun()'.          |
            <myfun()>           ID of a function defined in user's circuit file (see example below).                           |
            <parm>              array of pointers defined in NAPA netlist (ganging). Respect the order of function             |
                                parameters when GANGING BY POSITION! This function accepts also GANGING BY NAME.               |
                                If the module has no parameter, use 'NULL' keyword as array of pointers.                       |
            <tag>               is a tag used to link the SARC function to the functions extracting the outputs.               |
            <an_output_name_i>  is one of the output of the function 'myfun()' placed between parenthesis.                     |
            <outn>              is the output designated by <an_output_name> of the instance designated by <tag>.              |
                                                                                                                               |
            CAUTION!  Here, MAXIMA outputs V(abc), I(def), ... must be replaced respectively by (V@abc), (I@def), ...          |
                            MAXIMA outputs V(-gh), I(-ij), ... must be replaced respectively by (V@Mgh), (I@Mij), ...          |
                                                                                                                               |
      Header files containing functions like 'myfun()' are created by a MAXIMA script transforming a SPICE like netlist        |
      of linear elements in a set of arrays specially built to be used by the user function 'sarc'. Please consult             |
      documentation in directory '/Simulate/MaximaDos/Doc'.                                                                    |
                                                                                                                               |
      Example of NAPA netlist:                                                                                                 |
                                                                                                                               |
          header  <napatool.hdr>                                                                                               |
          ...                                                                                                                  |
          ...          +-------------------------------+-----------------------------------------------------------------------+
          ...          |                               |                                                                       |
          ...          v                               |                                                                       |
          header  "./myfun.hdr"                        |             // The header file containing the function 'myfun()' -----+
          ...                                          |             // corresponds to the circuit myfun() under test.
          ...                         `                |
          dvar     Rb   1.234                          |             // The function 'MIMO_myfun()' has been generated by a
          dvar     Ca   2.345                          |             // dedicated MAXIMA program from a netlist of passive
          dvar     L4   3.456                          |             // components R, L, C, independant sources V, I and
          dvar     Ra   4.567                          |             // controlled electrical sources E, F, G and H.
          ...                                          |
          ganging  myparm[]  Ca L4 4.567 Rb            |             // Caution for GANGING BY POSITION: order IS important!
          ...         |                                |             // Consult the header file to check order, here "myfun.hdr".
          ...         |                                |             // You may prefer ganging by name! (see below)
          ...         +--------------------------+     |
          ...                                    |     |
          update   Ca   5.678  when fire         |     |             // Parameters R,L,C,E,G,H,F may be updated during simulation.
          event  fire   ISTIME(2.0e-6)           |     |             // ISTIME() guarantees to catch once but only once the event.
          ...                                    |     |             // Here we are updating Ca when simulation time reaches 2us.
          node    vin   osc   0.0 1.0 6.789 0.0  |     |
          node    off   dc   -0.01               |     |
          ...                          +---------------+
          ...                          |         |
          ...                          v         v                   // Name 'myfun()' corresponds to function 'MIMO_myfun()'
          node  mytag   duser  sarc  myfun()  myparm  vin   offs     // located in the header file "./myfun.hdr".
          ...     |                                     ^     ^
          ...     |                                     |     |      // We suppose in this example that function 'myfun()' has
          ...     +--------------------+                +-----+----  //   2 inputs  in the model:  in, offs
          ...                          |      +--------------------  //   4 outputs in the model:  V@ZO, I@L4, I@Ca, V@MO1
          ...                          |      |
          ...                          v      v
          node    il4   duser  sarc  mytag  (I@L4)                   // output I@L4  corresponds to I(L4)  as defined in 'myfun()'
          node   vout   duser  sarc  mytag  (V@ZO)                   // output V@ZO  corresponds to V(ZO)  as defined in 'myfun()'
          node   vout   duser  sarc  mytag  (V@MO1)                  // output V@MO1 corresponds to V(-O1) as defined in 'myfun()'
          ...
          init   void   print_var(1.0/Rb, "S")
          init   void   print_var(Ca,     "F")
          ...
          debug  SARC                                                // to get debugging information on the sarc modules
          ping                                                       // it is a good idea to 'ping' functions for documentation.
          ...

          Example of GANGING BY NAME:

          ...
          dvar     Rb   1.234
          dvar     Ca   2.345
          dvar     L4   3.456
          ganging  myparm[]  Cin::Ca  R1::4.567  R2::Rb  Lout::L4    // Ganging by name.
          ...

          The main function call is not compatible with short form '&delayed'.

      Being a sophisticated function with multiple pointers defined at run time, it is recommended to use the debug facilities to
      check that parameters of the user sarc functions are transmitted in the appropriate order.

      Debug modes:   SARC                                            (recommended)
      with directive VERBOSE                                         (copies of the alphanumeric schematics of the hdr file)

Documentation in '..\User\sequence.hdr'

     NAPA iuser defined function:  "sequence"

     Generates an integer number from an interval of indices.

     USAGE: node <node_nam>  iuser  sequence       <n2>
            node <node_nam>  iuser  sequence       <n2>  (up)
            node <node_nam>  iuser  sequence       <n2>  (down)
            node <node_nam>  iuser  sequence       <n2>  (shuffle)
            node <node_nam>  iuser  sequence       <n2>  (shuffle)  (aperiodic)
            node <node_nam>  iuser  sequence       <n2>  (shuffle)  (periodic)
            node <node_nam>  iuser  sequence  <n1> <n2>
            node <node_nam>  iuser  sequence  <n1> <n2>  (up)
            node <node_nam>  iuser  sequence  <n1> <n2>  (down)
            node <node_nam>  iuser  sequence  <n1> <n2>  (shuffle)
            node <node_nam>  iuser  sequence  <n1> <n2>  (shuffle)  (aperiodic)
            node <node_nam>  iuser  sequence  <n1> <n2>  (shuffle)  (periodic)

     Where  n1   long integer, limit min of interval [n1, n2]  (default: 0)     @ init
            n2   long integer, limit max of interval [n1, n2]                   @ init

     Optional qualifiers are '(up)', '(down)', or '(shuffle)'.                  @ init
     It is possible to periodize the sequence '(periodic)' or '(aperiodic)',    @ init
     when using the option '(shuffle)'.

     defaults are '(up)' and '(aperiodic)'.

     Debug mode:    no specific directive

Documentation in '..\User\sine.hdr'

     Generalised sinewave  (COMPUTED AT END OF PHASE PHI1, END OF PHASE PHI2)

     [when it is necessary to simulate half period sampling of an input signal]

     NAPA duser defined function:  "sine"

     USAGE:
        node <nod>  duser  sine  <offset> <ampl> <freq> <phase>
        node <nod>  duser  sine  <offset> <ampl> <freq> <phase>  (phi1)
        node <nod>  duser  sine  <offset> <ampl> <freq> <phase>  (phi2)

        where:    <nod>       is the output node
                  <offset>    is the DC offset
                  <ampl>      is the amplitude peak
                  <freq>      is the frequency
                  <phase>     is the phase

                  <(opt)>     is (phi1), (phi2),  default is (phi1)

              :<-- NAPA PERIOD -->:
               _________           _________
              |         |         |         |
         _____|         |_________|         |_____

              :         :         :         :
          >>PHI1    >>PHI2    >>PHI1    >>PHI2

        Duty cycle is supposed to be 0.5 by default

        directive 'SINE_DUTY_CYCLE <xxx>' where <xxx> is a number in interval ]0.0, 1.0[ sets the duty cycle if necessary

     Debug mode:    no specific directive

Documentation in '..\User\stable.hdr'

       iuser function  'stable(..)'

       Check for the stabilization of a signal during last <num> local clock cycles.
       Signal may be analog or digital.

       May be used to terminate properly a simulation:

       USAGE:   node  <no>  iuser  stable  <sig >
                node  <no>  iuser  stable  <sig >  <num>
                node  <no>  iuser  stable  <sig >  <num>  <prec>

       Where    <sig>   is the signal to analyze the stabilization
                <num>   is the number of clock cycles to analyze (default 5)    @ init
                <prec>  is the relative precision of the comparison             @ init
                <no>    is the result (true or false).

                Default value for <prec> is currently 1.0e-6, which may be redefined by directive STABLE_PREC

                Note:   output will be 'false' until the number of local clock cycles is -at least- equal to <num>.

       EXAMPLE:         ...
                        node  y      ...
                        node  stop   iuser  stable  y  25  1.0e-3
                        ...
                        terminate    (1000000 < LOOP_INDEX) || stop

     Debug mode:    no specific directive

     Directive:         STABLE_PREC

Documentation in '..\User\sun.hdr'

     Compute the apparent position of the sun and a few other sun related data from geolocation, local time and time zone
     (include daylight saving time in time zone!). Elevation is corrected for atmospheric refraction.

     The effects of the atmosphere vary with atmospheric pressure, humidity and other variables. Therefore the exact solar
     position calculations presented represents approximately the apparent position of the sun. Errors in sunrise and sunset times
     can be expected to increase the further away you are from the equator, because the sun rises and sets at a very shallow angle.
     Small variations in the atmospheric refraction may have a larger effect.

         *****   CAUTION!       UNDERSTAND SIGN CONVENTIONS!!!  (see below)   *****

     USAGE:

     [Form A]
      node <tag_m> duser sun  <lat> <lon>  <year> <month> <day> <hour> <minute>  (tz::<n>) (dst::<yesno>)
               |
               +----------------+
                                |
      node <out_a> duser sun <tag_m>  (<option_1>)
      node <out_b> duser sun <tag_m>  (<option_2>)
      ...                       |
      node <out_j> duser sun <tag_m>  (<option_p>)

     [Form B]
      node <tag_n> duser sun  <lat> <lon>  <day2000> <decimal_hour>  (tz::<n>) (dst::<m>)
               |
               +----------------+
                                |
      node <out_a> duser sun <tag_n>  (<option_1>)
      node <out_b> duser sun <tag_n>  (<option_2>)
      ...                       |
      node <out_j> duser sun <tag_n>  (<option_q>)

      <lat>            latitude    -90.0, ..  90.0           [decimal degrees]
      <lon>            longitude  -180.0, .. 180.0           [decimal degrees]

         *** CAUTION!  Signs convention:    Northern hemisphere    latitude  [+]
                                            Southern hemisphere    latitude  [-]
                                            Eastern  hemisphere    longitude [+]     <<<< Greenwich
                                            Western  hemisphere    longitude [-]     <<<<

      <year>           4 digits
      <month>          JANUARY, .. DECEMBER    or   1, .. 12
      <day>            1, .. 31
      <hour>           0, .. 23
      <minute>         0, .. 59.999                          [decimal minutes]

      (tz::<n>)        -12.0, .. 12.0     optional parameter, default defined by macro TIME_ZONE (currently Mid Europe/Africa)
                                          NB: some time zones are not integer numbers (India for instance)
      (dst::<dvar-yesno>)   YES or NO     optional parameter, daylight saving time, YES or NO, default is NO

         *** CAUTION!  Sign convention:   Eastern  hemisphere    time_zone [+]       <<<<
                                          Western  hemisphere    time_zone [-]       <<<<

      <day2000>        number of days from year 2000,        [decimal days]
      <decimal_hour>   local time,                           [decimal hours]

      <tag_x>          output of first function call which is used as reference for following function calls.

      <out_i>          output according to option below:

     (<option_j>)      (azimuth)                             [decimal degrees]
                       (elevation), (elevation_max),  [ *]   [decimal degrees]
                       (altitude), (altitude_max),    [**]   [decimal degrees]
                       (equation_of_time)                    [decimal hours]
                       (transit_time)                        [decimal hours]
                       (shadow),                             [length relative to 1.0]
                       (energy),                             [energy/area relative to 1.0]
                       (universal_time), (local_time)        [decimal hours]
                       (days_y2k)                            [decimal days]

                               alias:  (noon) for (transit_time)

                       [ *] default option is (elevation)
                       [**] altitude is identical to elevation BUT 0.0 replaces negative values

      SUN
       |\         Elevation is 90° at zenith, 0° at horizon and -90° at nadir.
       | \        Azimuth is 0° at North, 90° at East, 180 at South, 270° at West.
       |  \
       |   \
       |    \
       |     \
       |     .\
       |   .   \
       |   elevation (angle)
       |__.______\_________               SUN
       \        .                           \
        \     azimuth (angle)                \
         \      .                             \
          \    .                               \
           \  .                                H\
            .                                  H.\
             \                                 H..\
            North                              H...\
                                               H....\       height of vertical stick = 1.0
                       . .\               1.0  H.....\      1.0 * shadow = tan(h)
                   . . . . \                   H......\
               . . . . . . .\                  H.......\
           . . . . . . . . . \                 H........\
         . . . . . . . . . . .\                H...   h = elevation (angle)
        \. . . . . . . . . . . \               H..........\
         \ . . SUN ENERGY  . . .\          ____H...........\________
          \. . . . . . . . . . . \                                  Horizontal Plane
           \ . . . . . . . . . . .\            ^  SHADOW   ^
            \. . . . . . . . . . . \
             \ . . . . . . . . . . .\
              \. . . . . . . . . . . \
               \ . . . . . . . . . . .\                     energy delivered at 90° = 1.0
                \. . . . . . . . . . . \                    energy on unit square   = 1.0 * sin(h)
                 \ . . . . . . . . h = elevation (angle)
                  \. . . . . . . . . . . \
            _______\_._._._._._._._._._._.\_________
                                                    Horizontal Plane
                   ^ ENERGY on unit square ^

                     SUN
                       \                              horizontal
                        \   270° West                 coordinates
                         \      |                     system
                          \     |
                           \    |
                           .\   |
                             \  |
                         .    \ |
                               \
      180° South  ------.-------o------.--------- 0° North
                               /|     .
                              / |    .
                       .     /     .
        (angle) ELEVATION   / . AZIMUTH (angle)
                           /
                          /     |
                       . /      |
                        /       |
                       .     90° East
                      /
                     /
                    /
            Projection of straight
            line [Observer, SUN] on
            horizontal plane [N,W,S,E]

      Twilight is not computed directly but elevations of sun corresponding to various definitions are provided,

        . Standard twilight           (apparent of the sun's upper limb touches horizon)
        . Civil twilight                 (impossible to read outside with ambient light)
        . Nautical twilight                (navigation using a sea horizon not possible)
        . Amateur astronomical twilight              (dark enough for many observations)
        . Astronomical twilight                                 (sky is completely dark)

      Available elevation macros corresponding to these twilights definitions (morning and evening twilights):
          TWILIGHT_STANDARD             = -SUN_RADIUS          [decimal degrees]
          TWILIGHT_CIVIL                = - 6.00               [decimal degrees]
          TWILIGHT_NAUTICAL             = -12.00               [decimal degrees]
          TWILIGHT_AMATEUR_ASTRONOMICAL = -15.00               [decimal degrees]
          TWILIGHT_ASTRONOMICAL         = -18.00               [decimal degrees]

      and the apparent diameter and radius of the sun:
          SUN_DIAMETER                  =   0.530              [decimal degrees]
          SUN_RADIUS                    =   0.265              [decimal degrees]

      To trigger the output of DEBUG information:

          'debug SUN'   which could be extended with  'directive VERBOSE'

      TIPS: - To get your latitude/longitude data, use tool like in    http://www.earthtools.org/
            - To debug/crosscheck:   http://www.srrb.noaa.gov/highlights/sunrise/azel.html
              [Sign conventions are different on this web site!]

            - Useful functions in included files:
                decimal_day (day, hour, minute, second)
                decimal_hour(day, hour, minute, second)
                dy2k(year, month, day, universal_time)

      Time Zones   (to be ADDED to GMT to get local time)

               local_time = universal_time + time_zone + daylight_saving_time

       -12     International Date Line
       -11     Pacific Ocean
       -10     Hawaii
        -9     Alaska Time
        -8     Pacific Standard Time
        -7     Mountain Standard Time
        -6     Central Standard Time
        -5     Eastern Standard Time
        -4     Atlantic Time
        -3.5   Newfoundland Time
        -3     Greenland Time
        -2     Atlantic Ocean
        -1     SE Greenland
         0     Greenwich, England
         1     Mid Europe/Africa
         2     Eastern Europe,  Eastern Central Africa
         3     Moscow,  Mid-East,  Eastern Africa
         3.5   Iran
         4     NW Caspian Sea
         4.5   Afghanistan
         5     Ural Mountains, Russia
         5.5   India
         6     Almaty (Alma ATA), Russia
         6.5   Burma
         7     Western Mongolia
         8     China
         9     Japan
         9.5   Mid Australia
        10     Eastern Russia,  Sydney, Australia
        11     Kamchatskiy, Eastern Russia

      This function is not compatible with short form '&delayed', add an external delay.

      TIPS:    Get time zones from     http://www.timeanddate.com/worldclock/full.html, and correct for daylight time savings.

      For a tutorial, see for instance http://www.stjarnhimlen.se/comp/tutorial.html

     Debug mode:    SUN

     Directives:    VERBOSE        (to augment debug information)
                    SUN_CORRECTION_FOR_AIR_REFRACTION
                       0            no correction
                       1 (default)  Reference:    http://www.srrb.noaa.gov/highlights/sunrise/calcdetails.html
                       2            Reference:    http://www.sci.fi/~benefon/azimalt.cpp

Documentation in '..\User\sweep.hdr'

     NAPA duser defined functions:
            "synchro_linsweep",  "synchro_logsweep",  "synchro_readsweep"

     Operations are SYNCHRONOUS to TOOL_INDEX: output changes when TOOL_INDEX changes.

     USAGE:

     node <node_nam> duser synchro_linsweep <lim1> <lim2> <nstp>
     node <node_nam> duser synchro_linsweep <lim1> <lim2> <nstp> (up)
     node <node_nam> duser synchro_linsweep <lim1> <lim2> <nstp> (down)
     node <node_nam> duser synchro_linsweep <lim1> <lim2> <nstp> (shuffle)
     node <node_nam> duser synchro_linsweep <lim1> <lim2> <nstp> (up)      <rate>
     node <node_nam> duser synchro_linsweep <lim1> <lim2> <nstp> (down)    <rate>
     node <node_nam> duser synchro_linsweep <lim1> <lim2> <nstp> (shuffle) <rate>
     node <node_nam> duser synchro_linsweep <lim1> <lim2> <nstp> (up)      <rate> <offset>
     node <node_nam> duser synchro_linsweep <lim1> <lim2> <nstp> (down)    <rate> <offset>
     node <node_nam> duser synchro_linsweep <lim1> <lim2> <nstp> (shuffle) <rate> <offset>

     node <node_nam> duser synchro_logsweep <lim1> <lim2> <nstp>
     node <node_nam> duser synchro_logsweep <lim1> <lim2> <nstp> (up)
     node <node_nam> duser synchro_logsweep <lim1> <lim2> <nstp> (down)
     node <node_nam> duser synchro_logsweep <lim1> <lim2> <nstp> (shuffle)
     node <node_nam> duser synchro_logsweep <lim1> <lim2> <nstp> (up)      <rate>
     node <node_nam> duser synchro_logsweep <lim1> <lim2> <nstp> (down)    <rate>
     node <node_nam> duser synchro_logsweep <lim1> <lim2> <nstp> (shuffle) <rate>
     node <node_nam> duser synchro_logsweep <lim1> <lim2> <nstp> (up)      <rate> <offset>
     node <node_nam> duser synchro_logsweep <lim1> <lim2> <nstp> (down)    <rate> <offset>
     node <node_nam> duser synchro_logsweep <lim1> <lim2> <nstp> (shuffle) <rate> <offset>

     node <node_nam> duser synchro_readsweep <filenam>
     node <node_nam> duser synchro_readsweep <filenam> <col>
     node <node_nam> duser synchro_readsweep <filenam> <col>  (up)
     node <node_nam> duser synchro_readsweep <filenam> <col>  (down)
     node <node_nam> duser synchro_readsweep <filenam> <col>  (shuffle)
     node <node_nam> duser synchro_readsweep <filenam> <col>  (up)      <rate>
     node <node_nam> duser synchro_readsweep <filenam> <col>  (down)    <rate>
     node <node_nam> duser synchro_readsweep <filenam> <col>  (shuffle) <rate>
     node <node_nam> duser synchro_readsweep <filenam> <col>  (up)      <rate> <offset>
     node <node_nam> duser synchro_readsweep <filenam> <col>  (down)    <rate> <offset>
     node <node_nam> duser synchro_readsweep <filenam> <col>  (shuffle) <rate> <offset>

     Where  lim1     real, limit min of interval [lim1, lim2].                  @ init
            lim2     real, limit max of interval [lim1, lim2].                  @ init
            filenam  file name containing the list of points.                   @ init
            col      is the column number of the 'Y' data, default 0.           @ init
            nstp     number of steps.                                           @ init
            rate     decimation rate of the trigger input, default 1.           @ init
            offset   offset of the decimation,             default 0.           @ init

            options are (up), (down) and (shuffle).                             @ init
            default is (up).

     Every line of the data file must be one of the following types:

            <y0>     <y1> ...     // any comment
            # any comment

     It means that if no tool is instantiated, this function will generate an error.
     Use the tool 'synchro' designed to manage this situation.

     It is possible to periodize the shuffled sequence:      directive SWEEP_PERIODIC.

     To redefine (with care!) the trigger mechanism, use:    directive SYNCHRO_SWEEP a_new_function

     NOTE:  The option 'shuffle' implements a QUASI-RANDOM number generator. This is highly recommended to organize simulations.

     EXAMPLE: generate sinewave sweeping amplitudes in a random manner (i.e. quasi-random), make analysis and sort results.

     title  "QUASI-RANDOM SWEEP OF AMPLITUDES"
     header <napa.hdr>
     header <toolbox.hdr>
     fs     1.0e6

     export ampldb

     node ampldb duser    synchro_linsweep   -100.0  0.0  11   (shuffle)
     node ampl   dalgebra db2lin(ampldb, 1.0)
     node out    sin      0.0  ampl  1234.0  0.0

     node void   itool    sinewave "foo.out" out 1.0  100000     // unsorted results
     post        sort     "stdout"  8                            //   sorted results

     terminate   11 <= TOOL_INDEX

        >>>>>  What are the ADVANTAGES of this method based on QUASI-RANDOM numbers?

        Making a traditional sweep (-100, -90, -80, .., -10, 0) of amplitudes could cause very subtle problems. If the module
        under test has some latencies or has a very large settling time, the analysis could be made too early (e.g. because
        'interlude' is missing or its value is too small).
        The amplitude of the output is not yet stable. As the amplitude steps between two analysis are constant, a systematic
        error is made, although the simulation and the results of the analysis may seem correct.

        Using QUASI-RANDOM numbers, we still perform the analysis with the same set of inputs (-100, -90, -80, .., -10,  0) but
        in a random manner (shuffled). Results of the simulation are postprocessed to sort the results properly. But the problem
        described above will cause random errors, as the steps between two analysis is no more a constant, revealing clearly the
        issue!

        These nodes should be preferred to functions 'linsweep' and 'logsweep' as they are automatically synchronized to the
        analysis tools (see file "control.hdr").

     Debug mode:    SYNCHRO_READSWEEP

     Directive:     SWEEP_PERIODIC

Documentation in '..\User\wave1.hdr'

     NAPA iuser defined function:  "wave1x16_in", "wave1x16_out"

     Reader/Writer of  One channel, PCM, Mono 16Bits '*.wav' Files

               CURRENTLY LIMITED TO A FEW WAVE FORMATS!!!!

     USAGE:

      node  <out>   iuser  wave1x16_in  <"fil_nam">                              from WAV file to <out>
      node  <npts>  iuser  wave1x16_out <"fil_nam">  <in>                        from <in> to WAV file

      Where <out>       is the digital output node        (see 0.0 dB reference below)
            <in>        is the digital input node         (see 0.0 dB reference below)
            <npts>      is the number of samples already output
            <"fil_nam"> is the pathname of the file containing the waveform     @ init

      It is important that the local sampling frequency of the simulation corresponds to the sampling frequency of the wave file
      being input. It is left to the responsibility of the user.

      'ON_READ_EOF_FLAG' is 'true' at the end of the file being read (aperiodic only).
      This macro may be used to control the simulation, e.g. in instruction 'terminate':

          header <napa.hdr>
          fs     44.1e3
          ..
          node npts  iuser  wave1x16_in  "foo.dat"     // with data sampled at 44.3 kHz
          ..
          terminate ON_READ_EOF_FLAG

      A warning is issued at the end of the simulation if a read overflow occurs somewhere in the simulation
      (see '../Resource/read.hdr')

      Macro constant WAVE1_REFERENCE (double) represents the 0dB reference of a WAV file.
      This macro cannot be redefined by user.

      TIPS: There are special formats of WAV files. To get a more standard format, convert the original file with freeware tools
            like 'format factory' the original file from WAV . It should produce file compatible with these NAPA user functions.
            Some WAV files are not following strict standard and are therefore "corrupted". Again freeware tools like
            'format factory' may be tolerant to some of these and could correct the code.

     Debug mode:    WAVE   WAVE1   WAVE1_IN   WAVE1_OUT

Documentation in '..\User\wave2.hdr'

     NAPA iuser defined function:  "wave2x16_in", "wave2x16_out"

     Reader/Writer of  One channel, PCM, Stereo 16Bits '*.wav' Files

               CURRENTLY LIMITED TO A FEW WAVE FORMATS!!!!

     USAGE:

      node  <out>   iuser  wave2x16_in  <"fil_nam">  (<option>)                  from WAV file to <out>
      node  <out>   iuser  wave2x16_in  <"fil_nam">                              from WAV file to <out>
      node  <npts>  iuser  wave2x16_out <"fil_nam">  <inl>  <inr>                from <inl> and <inr> to WAV file

      Where <out>       is the digital output node        (see 0.0 dB reference below)
            <inl>,<inr> are the digital input nodes       (see 0.0 dB reference below)
            <npts>      is the number of samples already output
            <"fil_nam"> is the pathname of the file containing the waveform     @ init

            (<option>)  (left), (right) or (add) identifies channel(s) to read
                        Default is (add) transforming a stereo signal in a mono signal.

      CAUTION:   There is a synchronization verification, left and right channels must be read synchronously.
                 Both channels must be read at the same rate!

      It is important that the local sampling frequency of the simulation corresponds to the sampling frequency of the wave2 file
      being input. It is left to the responsibility of the user.

      'ON_READ_EOF_FLAG' is true at the end of the file being read (aperiodic only).
      This macro may be used to control the simulation, e.g. in instruction 'terminate':

          header <napa.hdr>
          fs     44.1e3
          ..
          node  npts iuser  wave2x16_in  "foo.dat"  (add)   // with data sampled at 44.3 kHz
          ..
          terminate ON_READ_EOF_FLAG

      A warning is issued at the end of the simulation if a read overflow occurs somewhere in the simulation
      (see '../Resource/read.hdr')

      Macro constant WAVE2_REFERENCE (double) represents the 0dB reference of a WAV file. This macro cannot be redefined by user.

      TIPS: There are special formats of WAV files. To get a more standard format, convert the original file with freeware tools
            like 'format factory' from WAV . It should produce file compatible with these NAPA user functions.
            Some WAV files are not following strict standard and are therefore "corrupted". Again freeware tools like
            'format factory' may be tolerant to some of defects and could produce a correct code.

       Principle of Operation:

       2 modes of operation are possible:

       Mode stereo:

            node a  iuser  wave2x16  "infil.wav"  (left)
            node b  iuser  wave2x16  "infil.wav"  (right)

       Mode mono:

            node c  iuser  wave2x16  "infil.wav"  (add)

       It is not allowed to extract only 1 channel, i.e. only option (left) or (right) or to extract them in irregular chaotic way

     Debug mode:    WAVE   WAVE2  WAVE2_IN  WAVE2_OUT

Documentation in '..\User\wavefile.hdr'

     NAPA duser defined functions:  "wavefile"             (read an covert an analog piece wise linear waveform)

     This is the simplest way to create a waveform from a piece wise linear description contained in a file. A first order
     interpolation is used between points of this function to PRODUCE REGULARLY SAMPLED DATA. See also file "read1.hdr".

     ****  This user function is compatible with '.csv' files format  ****

           FYI, CSV stands for "Comma-Separated Values". It is a file format characterized by the representation of tabular data
           in plain text, where the values in each cell are separated by commas. Each line of the file represents a row
           in the table. This format is commonly used for importing and exporting data between different software applications,
           especially spreadsheet programs like Microsoft Excel or Google Sheets. In some cases, semicolons can also be used as
           separators, particularly in contexts where commas are used as decimal separators, (see below 'WAVEFILE_SEPARATOR').

     USAGE:

      node <ny>  duser  wavefile  <"fil_nam">  <tcol> <dcol>
      node <ny>  duser  wavefile  <"fil_nam">         <dcol>
      node <ny>  duser  wavefile  <"fil_nam">

      where <ny>        is the node output
            <"fil_nam"> is the pathname of the file containing the waveform                           @ init
            <tcol>      (1...) is the column number ot the time input,           default is 1         @ init
            <dcol>      (1...) is the column number of the waveform data,        default is 2         @ init

     Every line of the data file must be one of the following types:
            <d1>   <d2> ...      // any comment
            <d1> , <d2> ...      // any comment
            # any comment

     This analog waveform generator uses a FIRST ORDER INTERPOLATION when it is needed.

     'ON_READ_EOF_FLAG' is true if the time is above the last input time value of the description.
     IF it makes sense, this macro may be used to control the simulation, e.g. in instruction 'terminate' :

         header <napa.hdr>
         ..
         node y duser  wavefile  "foo.dat"  3  2
         ..
         terminate ON_READ_EOF_FLAG

     Directive:  WAVEFILE_NSTART <n>  start at line <nth>,                                default is 1  (start at very first line)
     Directive:  WAVEFILE_NSKIP  <m>  skip a maximum of <m> badly formatted lines if any, default is 1  (one bad line is allowed )
     Directive:  WAVEFILE_SEPARATOR   by default ',' the csv separator (and of course the space ' ')

     These directives, by default, are respectively defined by READ_NSTART and READ_NSKIP.

     Debug mode: WAVEFILE
     Directive:  VERBOSE              to augment debug information, a line by line report of the operations.

Documentation in '..\User\winlist.hdr'

     NAPA duser defined function:  "winlist"

      'winlist' generates a window padded xith zeroes and is used to evaluate the performances of this windowing function with FFT

                 /\
                /  \
               /    \
              /      \
             /        \________________________________________________
             num_points                   num_zeroes

     USAGE:
             num_points  num_zeroes
              __|___________|__
             |                 |
             |                 |
        n -->|     winlist      >---> out
             |                 |
             |_________________|

     node  <out>  duser winlist  <n>  <num_points>  <num_zeroes>

     Where  <n>            is the point to output
            <num_points>   is the number of points of the windows               @ init
            <num_zeroes>   is the number of zeroes of the windows               @ init

     Use   'directive WINDOW   <xxxx>'    to use windowing function <xxxx>
     Consult the list of available windowing functions in file "./Resource/winname.hdr"

     Debug mode WINDOWING_INFO provides information on the windowing function.
     This header uses file "window.hdr" containing normalized windowing functions.

Documentation in '..\User\wolfram_rule.hdr'

      NAPA iuser defined function:  "wolfram_rule"      for the 1D Cellular Automata Cell  <Cell/wolfram_rule.net>

      USAGE:  node  <out>  iuser  wolfram_rule  <rule_number>  <left> <center> <right>  &delayed

              where <rule_number>   Rule Descriptor defined by a decimal number in [0, 255]  (according to Wolfram's definition)
                    <left> <center> <right>    the three binary inputs

      EXAMPLE:  http://mathworld.wolfram.com/Rule158.html
                                                                                                 left   center  right
            1D Cellular Automata Cell, RULE 158                                                    |      |      |
                                                                                              _____v______v______v____
                  l c r      out                                                             |                        |
                  | | |       |                                                              |                        |
                  v v v       v                                                              |                        |
            7 =   1 1 1  ->   1  --------------------+                                       |   iuser wolfram_rule   |
            6 =   1 1 0  ->   0  ------------------+ :                                       |                        |
            5 =   1 0 1  ->   0  ----------------+ : :                                       |____________ ___________|
            4 =   1 0 0  ->   1  --------------+ : : :                                                    v
            3 =   0 1 1  ->   1  ------------+ : : : :                                                    |
            2 =   0 1 0  ->   1 -----------+ : : : : :                                                   out
            1 =   0 0 1  ->   1  --------+ : : : : : :
            0 =   0 0 0  ->   0  ------+ : : : : : : :
                                       : : : : : : : :
                                       v v v v v v v v
            Rule number (dec) 158  ==  0 1 1 1 1 0 0 1  (binary)

      +-------------------------------------------------------------------------------------------------------> 1
      :   +---------------------------------------------------------------------------------------------------< 35
      :   :         +------+         +------+         +------+         +------+         +------+         +--
      +---:--+  +---:--+---:--+  +---:--+---:--+  +---:--+---:--+  +---:--+---:--+  +---:--+---:--+  +---:--    etc..
      :  _:__:__:_  :  :  _:__:__:_  :  :  _:__:__:_  :  :  _:__:__:_  :  :  _:__:__:_  :  :  _:__:__:_  :
      : | 0  1  2 | :  : | 1  2  3 | :  : | 2  3  4 | :  : | 3  4  5 | :  : | 4  5  6 | :  : | 5  6  7 | :
      : |___1d____| :  : |___2d____| :  : |___3d____| :  : |___4d____| :  : |___5d____| :  : |___6d____| :
      :      :      :  :      :      :  :      :      :  :      :      :  :      :      :  :      :      :
      +------+------+  +------+------+  +------+------+  +------+------+  +------+------+  +------+------+
      :                :                :                :                :                |
      v                v                v                v                v                v
     1d               2d               3d               4d               5d               6d

     The directive 'debug WOLFRAM_RULE_DESCRIPTOR' triggers the output of a the Wolfram rule descriptor in binary format.

Documentation in '..\User\ztrans.hdr'

      NAPA duser defined function:  "ztrans"

      Used to model and simulate 'piecewise linear' circuits in time domain.

      >>> This header is using the 'ZTRANS' engine developped by JACQUES MEQUIN.

      This header is currently supporting circuits from 0 to max 12 inputs, and 1 output.

      The duser ztrans main function is called to compute the result.

        node  <out>   duser ztrans   <myfun()>  <parm>
        node  <out>   duser ztrans   <myfun()>  <parm>  <in1>
        node  <out>   duser ztrans   <myfun()>  <parm>  <in1> <in2>
        node  <out>   duser ztrans   <myfun()>  <parm>  <in1> <in2> <in3>
        node  <out>   duser ztrans   <myfun()>  <parm>  <in1> <in2> <in3> <in4>
        node  <out>   duser ztrans   <myfun()>  <parm>  <in1> <in2> <in3> <in4> <in5>
        node  <out>   duser ztrans   <myfun()>  <parm>  <in1> <in2> <in3> <in4> <in5> <in6>
        node  <out>   duser ztrans   <myfun()>  <parm>  <in1> <in2> <in3> <in4> <in5> <in6> <in7>
        node  <out>   duser ztrans   <myfun()>  <parm>  <in1> <in2> <in3> <in4> <in5> <in6> <in7> <in8>
        node  <out>   duser ztrans   <myfun()>  <parm>  <in1> <in2> <in3> <in4> <in5> <in6> <in7> <in8> <in9>
        node  <out>   duser ztrans   <myfun()>  <parm>  <in1> <in2> <in3> <in4> <in5> <in6> <in7> <in8> <in9> <in10>
        node  <out>   duser ztrans   <myfun()>  <parm>  <in1> <in2> <in3> <in4> <in5> <in6> <in7> <in8> <in9> <in10> <in11>
        node  <out>   duser ztrans   <myfun()>  <parm>  <in1> <in2> <in3> <in4> <in5> <in6> <in7> <in8> <in9> <in10> <in11> <in12>
                                         |
                                         +------------------------------------------------------------------------------+
          ...                                                                                                           |
                                                                                                                        |
     where  <in..>             inputs of the circuit (1 to 12) as specified in the definition of function 'myfun()'.    |
            <myfun()>          ID of a function defined in user's circuit file (see example below).                     |
            <parm>             array of pointers defined in NAPA netlist (ganging). Respect the order of function       |
                               parameters when GANGING BY POSITION! This function accepts also GANGING BY NAME.         |
                               If the module has no parameter, use 'NULL' keyword as array of pointers.                 |
            <an_output_name_i> is one of the output of the function 'myfun()' placed between parenthesis.               |
            <out>              is the output.                                                                           |
                                                                                                                        |
     Header files containing functions like 'myfun()' are created by a MAXIMA script transforming a SPICE like netlist  |
     of linear elements in a set of arrays specially built to be used by the user function 'ztrans'. Please consult     |
     documentation in directory '/Simulate/MaximaDos/Doc'.                                                              |
                                                                                                                        |
     Example of NAPA netlist:                                                                                           |
                                                                                                                        |
          header  <napatool.hdr>                                                                                        |
          ...                                                                                                           |
          ...          +-------------------------------+----------------------------------------------------------------+
          ...          |                               |                                                                |
          ...          v                               |                                                                |
          header  "./myfun.hdr"                        |              // The header file containing the function     'myfun()'
          ...                                          |              // corresponds to the circuit myfun() under test.
          ...                         `                |
          dvar     C4   1.2e-12                        |              // The function 'ZTRANS_myfun()' has been generated by a
          dvar     Ca   2.4e-12                        |              // dedicated MAXIMA program from a netlist of passive
          dvar     mu   0.001                          |              // components C, independant sources V, and voltage
          dvar    Av1   10.0e3                         |              // controlled voltage sources E.
          ...                                          |
          ganging  myparm[]  Ca C4 Av1 mu              |              // Caution for GANGING BY POSITION: order IS important!
          ...        |                                 |              // Consult the header file to check order, here "myfun.hdr".
          ...        |                                 |              // You may prefer ganging by name! (see below)
          ...        +-----------------------------+   |
          update  Av1   1.0e4  when fire           |   |              // Parameters of E sources may be updated during simulation.
          event  fire   ISTIME(2.0e-6)             |   |              // ISTIME() guarantees to catch once but only once the event.
          ...                                      |   |
          node    vin   osc   0.0 1.0 6.789 0.0    |   |
          node    off   dc   -0.01                 |   |
          ...                            +-------------+              // 'myfun()' corresponds to function 'ZTRANS_myfun()'
          ...                            |         |                  // which is located in the header file "./myfun.hdr".
          ...                            v         v
          node   vout   duser  ztrans  myfun()   myparm  vin1  vin2
          ...                                              ^     ^
          ...                                              |     |    // We suppose in this example that function 'myfun()' has
          ...                                              +-----+--  //   2 inputs :  inp, inm
          ...
          init   void   print_var(1.0/mu,  "")
          init   void   print_var(Ca,     "F")
          ...
          debug  ZTRANS                                               // to get debugging information on the ztrans modules
          ping                                                        // it is a good idea to 'ping' functions for documentation.
          ...

          Example of GANGING BY NAME:
          ...
          dvar    Av1   1.0e4
          dvar     Ca   2.345
          dvar     C4   3.456
          dvar     mu   0.001
          ganging  myparm[]  Cin::C4 C1::Ca M::mu A::Av1              // ganging by name.
          ...

      Being a sophisticated function with multiple pointers defined at run time, it is recommended to use the debug facilities to
      check that parameters of the user ztrans functions are transmitted in the appropriate order.

      Debug modes :     ZTRANS                                          (recommended)
      with directive    VERBOSE                                         (copies of the alphanumeric schematics of the header file)

NAPA user defined tools

Documentation in '..\Tool\benford.hdr'

     Benford's Law, also known as the law of anomalous numbers, states that in many naturally occurring datasets,
     the first digit of numbers follows a specific distribution: the digit `1` appears approximately 30.1% of the time, `2`
     appears about 17.6% of the time, and so on, down to `9` which appears roughly 4.6% of the time.

     Usage  node n  itool  benford  "fil_nam"  x  x_norm

     Where  <"fil_nam"> is the pathname of the output file                      @ init
            <x>         is the node to be analyzed
            <x_norm>    is the reference level for the analysis of <x>

     >>>>> The Benford's Law processes integers, therefore the values of (x / x_norm) should be integer to get a valid analysis.

     There is no EXPORT variable capability.

       THIS TOOL IS NOT SYNCHRONIZABLE

       Directive :   NO_BANNER

     *****************************************************************************************************************************

Documentation in '..\Tool\cfft0.hdr'

     NAPA itool defined functions:  "cwin"         'cwin' applies a window on a COMPLEX signal.

                                                          num_pnt
     USAGE:             __________                      _____|_
       __________      |          |    I (real)        |       |
      |          |     | module   |-------------------->       |
      | (signal) |-----> under    |    Q (imaginary)   |       |
      |__________|     | analysis |-------------------->       |
                       |__________|                    | CWIN  |
                                               I_norm ->       |
                                               Q_norm ->       |
                                                       |_______|

     node <no> itool  cwin  <"fil_nam">  <I> <I_norm> <Q> <Q_norm>  <num_pnt>

     Where  <"fil_nam"> is the pathname of the output file                      @ init
            <I>         is the node (real part) to be analyzed
            <I_norm>    is the reference level for the analysis of <I>
            <Q>         is the node (imaginary part) to be analyzed
            <Q_norm>    is the reference level for the analysis of <Q>
            <num_pnt>   is the number of points to analyze                      @ init
            <no>        is the number of single tasks already done by the tool

            export?     this tool handles only the first export variable defined by user

     This header uses file "window.hdr" containing normalized windowing functions.

     One parameter can be defined by 'directive': WINDOW
     Debug mode WINDOWING_INFO provides information on the windowing function.

     THIS TOOL IS SYNCHRONIZABLE

       Directive :   NO_BANNER
       Directive :   CWIN_NUM_INITIAL          <Integer_Number>

     *** CWIN TOOL OUTPUT ********************************************************************************************************

         packet   time   unweighted_R   unweighted_I   weighted_R     weighted_I
         + first export variable if any

Documentation in '..\Tool\cfft1.hdr'

     NAPA itool defined functions:  "cfft"

     'cfft' computes and output the FFT of a COMPLEX signal on a specified bandwidth.

     TIPS:  use itool 'cwin' to understand which signal itool 'cfft' is processing (see 'cfft0.hdr').

     USAGE:
                                                  fmin..fmax
                        __________                bandwidth  num_pnt
       __________      |          |                     _|____|_
      |          |     | netlist  |    I (real)        |        |
      | (signal) |-----> under    |-------------------->        |
      |__________|     | analysis |    Q (imaginary)   |        |
                       |          |-------------------->        |
                       |          |                    |  CFFT  |
                       |          |            I_norm ->        |
                       |          |                    |        |
                       |          |            Q_norm ->        |
                       |__________|                    |________|

     node <no> itool cfft <"fnam"> <I> <Inorm> <Q> <Qnorm>               <num_pnt>
     node <no> itool cfft <"fnam"> <I> <Inorm> <Q> <Qnorm> <bandwidth>   <num_pnt>
     node <no> itool cfft <"fnam"> <I> <Inorm> <Q> <Qnorm> <fmin> <fmax> <num_pnt>
     node <no> itool cfft <"fnam"> <I> <Inorm> <Q> <Qnorm>               <num_pnt> (<opt>)
     node <no> itool cfft <"fnam"> <I> <Inorm> <Q> <Qnorm> <bandwidth>   <num_pnt> (<opt>)
     node <no> itool cfft <"fnam"> <I> <Inorm> <Q> <Qnorm> <fmin> <fmax> <num_pnt> (<opt>)

     Where  <"fnam">    is the pathname of the output file                      @ init
            <I>         is the node (real part) to be analyzed
            <Inorm>     is the reference level for the analysis of <I>
            <Q>         is the node (imaginary part) to be analyzed
            <Qnorm>     is the reference level for the analysis of <Q>
            <bandwidth> is the bandwidth (to be plotted, to be analyzed...)     @ init
            <fmin>      is the min frequency of the bandwidth                   @ init
            <fmax>      is the max frequency of the bandwidth                   @ init
            <num_pnt>   is the number of points to analyze                      @ init
            <no>        is the number of single tasks already done by the tool

            (<opt>)     (window) or (no_window) for FFT processing, default is  (window)

            export?     the tool handles the full export list.

            Default value for bandwidth is  0 ... FSL

     Several parameters can be defined by 'directive': WINDOW, NCFFT,...
     Debug mode WINDOWING_INFO provides information on the windowing function.

     Sophisticated synchronization can be organized when mean of multiple FFT's is done. This is controlled by CFFT_OUTPUT_MODE.

     This header uses file "window.hdr" containing normalized windowing functions.

     Please note: FFT's are normalized versus POWER, not peak voltage .

     RMS of FFT is possible (directives NCFFT or REPEAT).

     Take care that windowing may introduce an error in the computation (e.g. DC level!).

     THESE TOOLS ARE SYNCHRONIZABLE

       Directive :   NO_BANNER

       Directive :   CFFT_NUM_INITIAL          <Integer_Number>
       Directive :   NCFFT                     <Integer_Number>

     Sophisticated synchronization can be organized when mean of multiple FFT's is done.
     This is controlled by CFFT_OUTPUT_MODE:

       directive CFFT_OUTPUT_MODE 0    increment output at completion of 'NFFT' FFT's
       directive CFFT_OUTPUT_MODE 1    increment output at completion of single FFT
       directive CFFT_OUTPUT_MODE 2    as 1, but output is reset at completion of each FFT

       Default for directive CFFT_OUTPUT_MODE is 0.

     CAUTION *********************************************************************************************************************

     The FFT algorithm is able to handle ANY numbers of samples.

      BUT   - power of 2 is recommended (the fastest)
            - FFT of multiple of small prime numbers are fast
            - But larger the prime numbers, slower the FFT!

     THUS if you notice that simulation is abnormally slow, check the number of data !!!

     *** CFFT TOOL OUTPUT ********************************************************************************************************

         packet        freq(Hz)    mag(dB)                 max?
         packet        freq(Hz)   mean(dB)   sigma3(dB)    max?
         + export variables if any

Documentation in '..\Tool\cgft1.hdr'

     NAPA itool defined function:    "cgft"      gft on a complex signal

       This tool computes the Fourier Transform of a signal at ONE frequency using the algorithm of GOERTZEL.
       The result is exactly the same as that given by the CFFT algorithm, but is faster because it only computes the desired
       point of the Fourier Transform. (see file 'Resource/goertzel.hdr' for further precisions)

       IT IS INTERESTING TO NOTE THAT THE FREQUENCY COULD BE ANYTHING AND DOES NOT NEED TO COINCIDE TO ONE OF THE FREQUENCY OF THE
       CORRESPONDING FFT BIN !!!

       The number of samples is arbitrary and does not need to be a power of 2.

       It is very important to note that the value given is also affected by the spread of the peaks due to non coherence and
       windowing effects. It is thus not possible to deduce the voltage corresponding to a peak from this single point.
       Use COHERENT SAMPLING!

       Several parameters can be defined by directives: 'WINDOW', 'NCGFT',...
       Debug mode WINDOWING_INFO provides information on the windowing function.

       RMS average of CGFT's is not possible.
       Debug mode WINDOWING_INFO provides information on the windowing function.

      USAGE:  node <no> itool cgft <"fnam"> <x> <xnorm> <y> <ynorm> <freq> <npnt> (<opt>)
              node <no> itool cgft <"fnam"> <x> <xnorm> <y> <ynorm> <freq> <npnt>

      where <"fnam">    is the pathname of the output file                      @ init
            <x>         is the node (real) to be analyzed
            <xnorm>     is the reference level for the analysis of <x>
            <y>         is the node (imaginary) to be analyzed
            <ynorm>     is the reference level for the analysis of <y>
            <freq>      is the frequency for which the DFT point is computed
            <npnt>      is the number of points to analyze                      @ init
            <no>        is the number of single tasks already done by the tool

            export?     this tool handles only the first export variable defined by user.

            (<opt>)     (window) or (no_window) for CGFT processing, default is (window)

                        __________            freq  num_pnt
       __________      |          |             _|__|_
      |          |     | module   |    x       |      |
      | (signal) |-----> under    |------------>      |
      |__________|     | analysis |    x_norm -> tool |
                       |          |            |      |
                       |          |------------>      |
                       |          |    y_norm-->      |
                       |__________|            |______|

       THIS TOOL IS SYNCHRONIZABLE

       Directive :   NO_BANNER

       Directive :   CGFT_NUM_INITIAL          <Integer_Number>

     *** CGFT TOOL OUTPUT ********************************************************************************************************

         packet        freq(Hz)     mag(dB)    arg(degree)
         + first export variable if any

Documentation in '..\Tool\collect.hdr'

     NAPA itool defined function:  "collect" collects and stores in array a number of samples of 1 or 2 signals

          To be used in conjunction with tools processing the data collected by this function

          ***** This is a DRAFT for a new class of functions which could evolve heavily in the future ***********************

     USAGE:
                            num_pnt
                       ______|__
         x            |         |
         ------------->         |
                      | collect |---> tag
             x_norm -->         |
                      |_________|    ....  data collected in array  'collect_record[tag].data1',
                                           and time in array        'collect_record[tag].data0' if requested by option (time)

                            num_pnt
                       ______|__
         x            |         |
         ------------->         |
                      |         |
             x_norm -->         |
                      |         |
                      | collect |---> tag
         y            |         |
         ------------->         |
                      |         |
             y_norm -->         |
                      |_________|    ....  data collected in arrays 'collect_record[tag].data1' and 'collect_record[tag].data2',
                                           and time in array        'collect_record[tag].data0' if requested by option (time)

     node  <tag>  itool  collect  <x> <x_norm>                <num_pnt>
     node  <tag>  itool  collect  <x> <x_norm>                <num_pnt>   (<option>)
     node  <tag>  itool  collect  <x> <x_norm>  <y> <y_norm>  <num_pnt>
     node  <tag>  itool  collect  <x> <x_norm>  <y> <y_norm>  <num_pnt>   (<option>)

     Where <x>           is the node to be collected
           <x_norm>      is the reference level of <x>
           <num_pnt>     is the number of points to be collected                               @ init
           <y>           is a second node to be collected
           <y_norm>      is the reference level of <y>
           <num_pnt>     is the number of points to be collected                               @ init
           <tag>         is the tag assigned to the data array by this tool

          (<option>)     (time) or (no_time) to control the collection of sampling times       @ init
                         default is (no_time)

     Example:

          ...
          node  tag3  itool  collect   x 1.0          1000000
          node  tag5  itool  collect   y 1.0  n 1024   250000  (time)
          ...
          tool  atool1  "myfile_1.out"  tag3  someparameters1                   // tool built to work with tool 'collect'
          tool  atool2  "myfile_2.out"  tag3  someparameters2  (someoption)     // tool built to work with tool 'collect'
          ...
          tool  atooln  "myfile_n.out"  tag5  someparametersn                   // tool built to work with tool 'collect'
          ...
          terminate   4 <= TOOL_INDEX

     THIS TOOL IS SYNCHRONIZABLE

       Directive :   COLLECT_NUM_INITIAL       <Integer_Number>

     *** TOOL OUTPUT IN ARRAYS, NOT IN A FILE ************************************************************************************

Documentation in '..\Tool\disto0.hdr'

     NAPA itool defined functions:  "freq"

      'freq'     computes the best estimate of the frequency of a sinewave, the correponding period and the oversampling ratio

      USAGE:

        ampl frq...      __________           frq  num_pnt
       __|_____|_       |          |           _|__|_
      |          |      | module   |  x       |      |
      | Sinewave  >-----> under    |----------> tool |
      |__________|      | analysis |  x_norm ->      |
                        |__________|          |______|

      node <nout> itool freq   <"fil_nam">  <x> <x_norm>  <num_pnt>

      where <"fil_nam"> is the pathname of the output file                      @ init
            <x>         is the node to be analyzed
            <x_norm>    is the reference level for the analysis of <x>
            <num_pnt>   is the number of points to analyze                      @ init
            <nout>      is the number of single tasks already done by the tools

            export?     this tool handles the full export list defined by user

     THIS TOOL IS SYNCHRONIZABLE

       Directive :   NO_BANNER

       Directive :   FREQ_NUM_INITIAL          <Integer_Number>

     *** FREQ TOOL OUTPUT ********************************************************************************************************

         packet   frequency  period   OSR
         + export variables if any

     ANALYSIS IN THE TIME DOMAIN OF A SINEWAVE WAVEFORM

Documentation in '..\Tool\disto1.hdr'

     NAPA itool defined functions:  "sinewave", "disto", "hdecomp"

      'sinewave' extracts the best sinewave fitting the signal under analysis.
      'disto'    evaluates the signal to distortion ratio.
      'hdecomp'  decomposes signal in offset, fundamental, harmonics and residues.

      TIPS: Use itool 'hdecomp' to understand what itool 'disto' is doing.

      USAGE:

        ampl frq...      __________           frq  num_pnt
       __|_____|_       |          |           _|__|_
      |          |      | module   |  x       |      |
      | Sinewave  >-----> under    |----------> tool |
      |__________|      | analysis |  x_norm ->      |
                        |__________|          |______|

      node <nout> itool sinewave <"fil_nam">  <x> <x_norm>  <frq>   <num_pnt>
      node <nout> itool sinewave <"fil_nam">  <x> <x_norm>          <num_pnt>

      node <nout> itool disto    <"fil_nam">  <x> <x_norm>  <frq>   <num_pnt>
      node <nout> itool disto    <"fil_nam">  <x> <x_norm>          <num_pnt>

      node <nout> itool hdecomp  <"fil_nam">  <x> <x_norm>  <frq>   <num_pnt>
      node <noit> itool hdecomp  <"fil_nam">  <x> <x_norm>          <num_pnt>

      where <"fil_nam"> is the pathname of the output file                      @ init
            <x>         is the node to be analyzed
            <x_norm>    is the reference level for the analysis of <x>
            <frq>       is the EXACT frequency of the input wave (optional)
            <num_pnt>   is the number of points to analyze                      @ init
            <nout>      is the number of single tasks already done by the tools

      export?   the tool 'hdecomp' handles only the first export variable defined by user
                the other tools handle the full export list defined by user

        result:  off + (r * sin(2*PI*f*t + phi))
        or       off + (r * sin(2*PI*f*(t-delay)))

      THESE TOOLS ARE SYNCHRONIZABLE

       Directive :   NO_BANNER

       Directive :   SINEWAVE_NUM_INITIAL      <Integer_Number>

       Directive :   DISTO_NUM_INITIAL         <Integer_Number>
       Directive :   HARMONICS                 <Integer_Number>           (default 3)

       Directive :   HDECOMP_NUM_INITIAL       <Integer_Number>
       Directive :   HPERIODS                  <Integer_Number>           (default 3)

       Debug Mode:   GAUSS_MATRIX    triggers the output of a debug information table.

     *** SINEWAVE TOOL OUTPUT ****************************************************************************************************

         packet        freq(Hz)   offset  amplitude   phase    delay    residue
         + export variables if any

     *** DISTO TOOL OUTPUT *******************************************************************************************************

         packet        freq(Hz)   snr(dB)      sdr(dB)     sndr(dB)   harm[0]  harm[1]..
         + export variables if any

     *** HDECOMP TOOL OUTPUT *****************************************************************************************************

         packet   time(s)  signal  harm[0]  harm[1]...  harm[ALL]  residue[0]  residue[1] ...
         + first export variable if any

     ANALYSIS IN THE TIME DOMAIN OF A SINEWAVE WAVEFORM. IT IS ALWAYS A GOOD IDEA TO USE COHERENT SAMPLING.

     *****************************************************************************************************************************
     PRINCIPLE of the Harmonic Decomposition:

     Signal under test should be a sort of sinewave. If the circuit under test is perfect this sinewave shpud be pure. Circuit
     under test being not perfect, the harmonic decomposition extracts and quantifies harmonics and noise.

     Tool is first extracting the frequency of the fundamental if the user has not provided any value.

     First, offset (called harm[0]) is extracted from the signal under test,
     the substraction of this signal and harm[0] gives a residue     (called residue[0]).

     From residue[0], amplitude and phase of the fundamental are extracted,
     the fundamental in time domain is then reconstructed            (called harm[1]).
     The substraction of residue[0] and harm[1] gives a new residue  (called residue[1]).

     From residue[1], amplitude and phase of the second harmonics are extracted,
     the second harmonics in time domain is then reconstructed       (called harm[2]).
     The substraction of residue[1] and harm[2] gives a new residue  (called residue[2]).

     From residue[2], amplitude and phase of the third harmonics are extracted,
     the third harmonics in time domain is then reconstructed        (called harm[3]).
     The substraction of residue[2] and harm[3] gives a new residue  (called residue[3]).

     The process is repeated for the other harmonics...
     The last residue is considered to be the residual noise of the signal.

     User must choose to continue the process until all relevant harmonics are extracted.

     From the value of amplitudes, the signal to distorsion is computed.
     The power of the final residue is computed and gives the power of the noise.

Documentation in '..\Tool\disto2.hdr'

     NAPA itool defined functions:  "im2", "i2decomp"

      'im2'        Evaluates the intermodulation products (f2-f1, f1+f2).
      'i2decomp'   Extracts fundamentals and intermodulation products (f2-f1, f1+f2).

      TIPS:        Use iool 'i2decomp' to understand what itool 'im2' is doing.
                   See also tools 'im3' and 'i3decomp'.

      USAGE:

       ampl1   freq1...
         _|_____|_
        |         |          __________            freq1 freq2  num_pnt
        |Sinewave1 >--+     |          |            _|____|_______|_
        |_________|   |     | module   |   x       |                |
         _________   (+)----> under    |----------->      tool      |
        |         |   |     | analysis |   x_norm ->                |
        |Sinewave2 >--+     |__________|           |________________|
        |_________|
          |     |
       ampl2   freq2...

      node <no> itool im2        <"fil_nam">  <x> <x_norm>  <freq1> <freq2>   <num_pnt>
      node <no> itool i2decomp   <"fil_nam">  <x> <x_norm>  <freq1> <freq2>   <num_pnt>

      where <"fil_nam"> is the pathname of the output file                      @ init
            <x>         is the node to be analyzed
            <x_norm>    is the reference level for the analysis of <x>
            <freq1,2>   are the EXACT frequencies of the 2 input waves
            <num_pnt>   is the number of points to analyze                      @ init
            <no>        is the number of single tasks already done by the tools

      export?   the tool 'im2' handles the full export list defined by user
                the tool 'i2decomp' handles only the first export variable defined by user

      The input is the sum of two sinewaves,
      the output contains intermodulation products if the netlist under analysis is non linear (2nd order non linearities, ..):

              f1  f2
               .  .                                                 f1  f2
               |  |             ___________________                  .  .
               |  |            |                   |                 |  |
               |  |          ==| non-linear device |==>     f2-f1    |  |      f1+f2
               |  |            |___________________|          .      |  |   2f1  .  2f2
         ______|__|_______                                 0__|______|__|_____|__|__|_
                df        freq                              df        df       df df  freq

       2nd order harmonics: 2f1 and 2f2
       2nd order intermodulation product:   f2-f1 and f1+f2

      Determination of the input intersection point IP2:  Use 'im2', varying input amplitudes.
      IP2 CONCEPT IS VALID ONLY FOR WEAKLY NONLINEAR SYSTEMS!!!

      amplitude at output (dB)
         |
         |                    .  (i)
         |          .         .   :      Main = sum of the 2 fundamentals
         |.  main         .       :      Side = sum of closest intermodulation products
         |            .           :
         |         .   side       :      Extrapolation gives the intersection point '(i)'.
         |      .                 :      Point (i) determines the IP2 on X axis.
         |   .                    :
         |.                       :
         |                        :
         |                        :
         |________________________v_________________
                                                    amplitude of input (dB)
                                 IP2

      THESE TOOLS ARE SYNCHRONIZABLE

       Directive :   NO_BANNER

       Directive :   IM2_NUM_INITIAL           <Integer_Number>

       Directive :   I2DECOMP_NUM_INITIAL      <Integer_Number>
       Directive :   I2PERIODS                 <Integer_Number>                  (default 3)

       Debug Mode:   GAUSS_MATRIX    triggers the output of a debug information table.

     *** IM2 TOOL OUTPUT *********************************************************************************************************

         packet left_par2(Hz) left_par2(dB) left_sig(Hz) left_sig(dB) right_sig(Hz) right_sig(dB)
                right_par2(Hz) right_par2(dB)  sig(dB) par2(dB)
         + export variables if any

     *** I2DECOMP TOOL OUTPUT ****************************************************************************************************

         packet  time  signal   offset   left    sig1   sig2  right
         + first export variable if any

     ANALYSIS IN THE TIME DOMAIN

Documentation in '..\Tool\disto3.hdr'

     NAPA itool defined functions:  "im3", "i3decomp"

      'im3'        Evaluates the intermodulation products (2*f1-f2, 2*f2-f1).
      'i3decomp'   Extracts fundamentals and intermodulation products (2*f1-f2, 2*f2-f1).

      TIPS:        Use itool 'i3decomp' to understand what itool 'im3' is doing.
                   See also tools 'im2' and 'i2decomp'.

      USAGE:

       ampl1   freq1...
         _|_____|_
        |         |          __________            freq1 freq2  num_pnt
        |Sinewave1 >--+     |          |            _|____|_______|_
        |_________|   |     | module   |   x       |                |
         _________   (+)----> under    |----------->      tool      |
        |         |   |     | analysis |   x_norm ->                |
        |Sinewave2 >--+     |__________|           |________________|
        |_________|
          |     |
       ampl2   freq2...

      node <no> itool im3        <"fil_nam">  <x> <x_norm>  <freq1> <freq2>   <num_pnt>
      node <no> itool i3decomp   <"fil_nam">  <x> <x_norm>  <freq1> <freq2>   <num_pnt>

      where <"fil_nam"> is the pathname of the output file                      @ init
            <x>         is the node to be analyzed
            <x_norm>    is the reference level for the analysis of <x>
            <freq1,2>   are the EXACT frequencies of the 2 input waves
            <num_pnt>   is the number of points to analyze                      @ init
            <no>        is the number of single tasks already done by the tools

      export?   the tool 'im3' handles the full export list defined by user
                the tool 'i3decomp' handles only the first export variable defined by user

      The input is the sum of two sinewaves,
      the output contains intermodulation products if the netlist under analysis is non linear (3rd order non linearities, ..):

              f1  f2
               .  .                                                f1  f2
               |  |             ___________________                 .  .
               |  |            |                   |                |  |
               |  |          ==| non-linear device |==>    2*f1-f2  |  |  2*f2-f1
               |  |            |___________________|             .  |  |  .
         ______|__|_______                                   ____|__|__|__|_______
                df        freq                                    df df df        freq

       3rd order harmonics: 3f1 and 3f2
       3rd order intermodulation product:  2f1-f2 and 2f2-f1
       3rd order intermodulation product:  2f1+f2 and 2f2+f1   (out of band of interest)

      Determination of the input intersection point IP3:  Use 'im3', varying input amplitudes.
      IP3 CONCEPT IS VALID ONLY FOR WEAKLY NONLINEAR SYSTEMS!!!

      amplitude at output (dB)
         |
         |                    .  (i)
         |          .         .   :      Main = sum of the 2 fundamentals
         |.  main         .       :      Side = sum of closest intermodulation products
         |            .           :
         |         .   side       :      Extrapolation gives the intersection point '(i)'.
         |      .                 :      Point (i) determines the IP3 on X axis.
         |   .                    :
         |.                       :
         |                        :
         |                        :
         |________________________v_________________
                                                    amplitude of input (dB)
                                 IP3

      THESE TOOLS ARE SYNCHRONIZABLE

       Directive :   NO_BANNER

       Directive :   IM3_NUM_INITIAL           <Integer_Number>

       Directive :   I3DECOMP_NUM_INITIAL      <Integer_Number>
       Directive :   I3PERIODS                 <Integer_Number>               (default 3)

       Debug Mode:   GAUSS_MATRIX    triggers the output of a debug information table.

     *** IM3 TOOL OUTPUT *********************************************************************************************************

         packet left_par3(Hz) left_par3(dB) left_sig(Hz) left_sig(dB) right_sig(Hz) right_sig(dB)
                right_par3(Hz) right_par3(dB)  sig(dB) par3(dB)
         + export variables if any

     *** I3DECOMP TOOL OUTPUT ****************************************************************************************************

         packet  time  signal   offset   left    sig1   sig2  right
         + first export variable if any

     ANALYSIS IN THE TIME DOMAIN

Documentation in '..\Tool\fft0.hdr'

     NAPA itool defined function:  "win"

      'win' applies the specified windowing function to the signal in the time domain (no FFT).

     USAGE:
                        __________              num_pnt
       __________      |          |             ___|_
      |          |     | module   |    x       |     |
      | (signal) |-----> under    |------------>     |
      |__________|     | analysis |            | win |
                       |__________|    x_norm ->     |
                                               |_____|

     node <no> itool win   <"fil_nam">  <x> <x_norm>  <num_pnt>

     Where  <"fil_nam"> is the pathname of the output file                      @ init
            <x>         is the node to be analyzed
            <x_norm>    is the reference level for the analysis of <x>
            <num_pnt>   is the number of points to analyze                      @ init
            <no>        is the number of single tasks already done by the tool

            export?     this tool handles only the first export variable defined by user

     Use   'directive WINDOW   <xxxx>'    to use windowing function <xxxx>
     Consult the list of available windowing functions in file "./Resource/winname.hdr"

     Debug mode WINDOWING_INFO provides information on the windowing function.
     This header uses file "window.hdr" containing normalized windowing functions.

     THIS TOOL IS SYNCHRONIZABLE

       Directive :   NO_BANNER

       Directive :   WIN_NUM_INITIAL           <Integer_Number>

     *** WIN TOOL OUTPUT *********************************************************************************************************

         packet   time(s)  unweighted    weighted

         + first export variable if any

Documentation in '..\Tool\fft1.hdr'

     NAPA itool defined functions:  "fft",  "ps"

      'fft'  computes and output the FFT on a specified bandwidth.
      'ps'   computes and accumulates the power spectrum on a specified bandwidth.

      TIPS:  use itool 'win' to understand which signal 'fft' is processing.

     USAGE:

                                          fmin..fmax
                        __________        bandwidth  num_pnt
       __________      |          |             _|____|_
      |          |     | module   |    x       |        |
      | (signal) |-----> under    |------------>        |
      |__________|     | analysis |            |  tool  |
                       |__________|    x_norm ->        |
                                               |________|

     node <no> itool fft     <"fil_nam">  <x> <x_norm>                 <num_pnt>
     node <no> itool fft     <"fil_nam">  <x> <x_norm>  <bandwidth>    <num_pnt>
     node <no> itool fft     <"fil_nam">  <x> <x_norm>  <fmin> <fmax>  <num_pnt>
     node <no> itool fft     <"fil_nam">  <x> <x_norm>                 <num_pnt>  (<opt>)
     node <no> itool fft     <"fil_nam">  <x> <x_norm>  <bandwidth>    <num_pnt>  (<opt>)
     node <no> itool fft     <"fil_nam">  <x> <x_norm>  <fmin> <fmax>  <num_pnt>  (<opt>)

     node <no> itool ps      <"fil_nam">  <x> <x_norm>                 <num_pnt>
     node <no> itool ps      <"fil_nam">  <x> <x_norm>  <bandwidth>    <num_pnt>
     node <no> itool ps      <"fil_nam">  <x> <x_norm>  <fmin> <fmax>  <num_pnt>
     node <no> itool ps      <"fil_nam">  <x> <x_norm>                 <num_pnt>  (<opt>)
     node <no> itool ps      <"fil_nam">  <x> <x_norm>  <bandwidth>    <num_pnt>  (<opt>)
     node <no> itool ps      <"fil_nam">  <x> <x_norm>  <fmin> <fmax>  <num_pnt>  (<opt>)

     Where  <"fil_nam"> is the pathname of the output file                      @ init
            <x>         is the node to be analyzed
            <x_norm>    is the reference level for the analysis of <x>
            <bandwidth> is the bandwidth                                        @ init
            <fmin>      is the min frequency of the frequency bandwidth         @ init
            <fmax>      is the max frequency of the frequency bandwidth         @ init
            <num_pnt>   is the number of points to analyze                      @ init
            <no>        is the number of single tasks already done by the tool

            (<opt>)     (window) or (no_window) for FFT processing,                         default is  (window)
                        (linear) or (dB) for tool 'fft' only                                default is  (dB)
                        only for fft:  (psophometric), (audiometric) or (no_filtering),     default is  (no_filtering)

            export?     the tools handle the full export list.

            Default value for bandwidth is  0 ... Nyquist

     Use   'directive WINDOW   <xxxx>'    to use windowing function <xxxx>
     Consult the list of available windowing functions in file "./Resource/winname.hdr"
     Take care that windowing may introduce artefacts in the computation (e.g. DC level!)

     Debug mode WINDOWING_INFO provides information on the windowing function.

     RMS average of FFT's is possible:

     Use respectively directives 'NFFT', 'NPS'. Their common default value is the value of the directive 'REPEAT' which has itself
     a default value of 1.

     >>>>> FFT's are normalized versus POWER, not peak voltage.

     THESE TOOLS ARE SYNCHRONIZABLE

       Directive :   NO_BANNER

       Directive :   FFT_NUM_INITIAL           <Integer_Number>
       Directive :   NFFT                      <Integer_Number>

       Directive :   PS_NUM_INITIAL            <Integer_Number>
       Directive :   NPS                       <Integer_Number>

     More sophisticated synchronization can be organized when averaging multiple FFT's (advanced users).
     This is controlled by directive:

       directive FFT_OUTPUT_MODE 0    increment output at completion of 'NFFT' FFT's
       directive FFT_OUTPUT_MODE 1    increment output at completion of each single FFT
       directive FFT_OUTPUT_MODE 2    as 1, but output is reset at completion of each FFT
       Default for directive 'FFT_OUTPUT_MODE' is 0.

       directive PS_OUTPUT_MODE 0     increment output at completion of 'NPS' PS's
       directive PS_OUTPUT_MODE 1     increment output at completion of each single PS
       directive PS_OUTPUT_MODE 2     as 1, but output is reset at completion of each PS
       Default for directive 'PS_OUTPUT_MODE' is 0.

     >>>>> CAUTION

     The FFT algorithm is able to handle ANY numbers of samples.

     BUT  - power of 2 is recommended (the fastest)
          - FFT of multiple of small prime numbers are fast
          - But larger the prime numbers, slower the FFT!

     THUS if you notice that FFT is abnormally slow, check if the factorization of the number of points contains large primes !!!

     *** FFT TOOL OUTPUT *********************************************************************************************************

         packet        freq(Hz)        mag    max?
         packet        freq(Hz)    mag(dB)    max?
         packet        freq(Hz)       mean       sigma3   max?
         packet        freq(Hz)   mean(dB)   sigma3(dB)   max?
         + export variables if any

     *** PS TOOL OUTPUT **********************************************************************************************************

         packet   frequency        mag(dB)    accumul(dB)     percentage
         packet   frequency       mean(dB)    accumul(dB)     percentage
         + export variables if any

Documentation in '..\Tool\fft10.hdr'

     NAPA itool defined function:  "enbw"

      'enbw'  computes the Equivalent Noise BandWidth of the module (filter) under test.

      The preferred way to use the method to get this equivalent bandwidth is to apply a WHITE NOISE at the input of the netlist
      under analysis and ask ta avarage FFTs to smooth the results. (Use directive REPEAT nn for example). But any input signal
      containing a power spread in all the bandwidth of interest could be used.

     >>> Valid ONLY for 'fairly' linear circuits,

      Do not forget to verify the impulse response to assess this evaluation!

      USAGE:

      node <no> itool enbw  <"fil_nam"> <x> <x_norm> <y> <y_norm> <maxt> <num_pnt>
      node <no> itool enbw  <"fil_nam"> <x> <x_norm> <y> <y_norm>        <num_pnt>
      node <no> itool enbw  <"fil_nam"> <x> <x_norm> <y> <y_norm> <maxt> <num_pnt>  (<opt>)
      node <no> itool enbw  <"fil_nam"> <x> <x_norm> <y> <y_norm>        <num_pnt>  (<opt>)

      where <"fil_nam"> is the pathname of the output file                      @ init
            <x>         is the input node
            <x_norm>    is the reference level for the analysis of <x>
            <y>         is the the output node
            <y_norm>    is the reference level for the analysis of <y>
            <maxt>      is the interval of time to be analyzed (optional)       @ init
            <num_pnt>   is the number of points to analyze                      @ init
            <no>        is the number of single tasks already done by the tool

            (<opt>)     (window) or (no_window) for FFT processing, default is  (window)

            export?     the tool handles the full export list.

      Several parameters can be defined by 'directive': WINDOW, NENBW, ...
      NENBW (default: REPEAT) determines the number of sub FFT's used to obtain the result

       _________         __________                 num_pnt
      |         |       |          |             ______|_
      | (white) |       | module   |    y       |        |
      | noise   |---+---> under    |------------>        |
      | source  |   |   | analysis |    y_norm ->        |
      |_________|   |   |__________|            |        |
                    |                           |  enbw  |
                    |                   x       |        |
                    +--------------------------->        |
                                        x_norm ->        |
                                                |________|

       THIS TOOL IS SYNCHRONIZABLE

       Directive :   NO_BANNER

       Directive :   ENBW_NUM_INITIAL          <Integer_Number>
       Directive :   NENBW                     <Integer_Number>

     FYI, Equivalent Noise Bandwidth as a function of the number of poles in the system response:
        ________________________________________________________________________
       | Number of Poles  |  Rolloff dB/Decade  |   Equivalent Noise Bandwidth  |
       |               1  |                -20  |                1.57 * f@-3dB  |
       |               2  |                -40  |                1.22 * f@-3dB  |
       |               3  |                -60  |                1.15 * f@-3dB  |
       |               4  |                -80  |                1.13 * f@-3dB  |
       |               5  |               -100  |                1.11 * f@-3dB  |
       |__________________|_____________________|_______________________________|

     *** ENBW TOOL OUTPUT ********************************************************************************************************

         packet        enbw
         + export variables if any

Documentation in '..\Tool\fft11.hdr'

      NAPA associated twin itool defined functions:  "resp2_i", "resp2_o"

      Multirate impulse and step functions

      Pair of 'resp2_i' and 'resp2_o' computes the impulse and step responses from input and output sampled at DIFFERENT rates.

      The preferred way to estimate these responses is to apply a WHITE NOISE at the input of the netlist under analysis and
      asking for a mean of FFTs to smooth the results. But any input signal containing a power spread in the bandwidth of interest
      could be used.

      These tools must be instantiated by pair!
          ->    'resp2_i' picks the  input.
          ->    'resp2_o' picks the output.

      USAGE:

      node  <ni>  itool  resp2_i  <"nam">  <nod_1> <norm_1>            <num>
      node  <ni>  itool  resp2_i  <"nam">  <nod_1> <norm_1>  <maxt>    <num>
      node  <ni>  itool  resp2_i  <"nam">  <nod_1> <norm_1>            <num> (<opt>)
      node  <ni>  itool  resp2_i  <"nam">  <nod_1> <norm_1>  <maxt>    <num> (<opt>)
              ...
      node  <no>  itool  resp2_o  <"nam">  <nod_2> <norm_2>            <num>
      node  <no>  itool  resp2_o  <"nam">  <nod_2> <norm_2>  <maxt>    <num>
      node  <no>  itool  resp2_o  <"nam">  <nod_2> <norm_2>            <num> (<opt>)
      node  <no>  itool  resp2_o  <"nam">  <nod_2> <norm_2>  <maxt>    <num> (<opt>)

      Where <"fnam">    is the pathname of the output file                      @ init
            <num>       is the number of points to analyze                      @ init
            <nod_1>     is the input node
            <norm_1>    is the reference level for the analysis of <x>
            <nod_2>     is the output node
            <norm_2>    is the reference level for the analysis of <y>
            <ni>        is the number of single tasks already done by the tool resp2_i
            <no>        is the number of single tasks already done by the tool resp2_o
            <maxt>      is the interval of time to be analyzed (optional)       @ init

            (<opt>)     (window) or (no_window) for FFT processing, default is  (window)

            export?     these tools does not handle export variable

            Default value for bandwidth is  0 ... Nyquist

       <filnam> MUST be the same for corresponding twin tools.
       <num>    MUST be the same for corresponding twin tools.
       <maxt>   MUST be the same for corresponding twin tools.
      (<opt>)   MUST be the same for corresponding twin tools.

       Due to the complexity of the synchronization mechanism, it is mandatory to base the control of the simulation on variable
       'TOOL_INDEX' and not on the value of the tool output nodes <ni> or <no>.

       Tools 'resp2_i' and 'resp2_o' may be placed in any order in the netlist.

       THESE TOOLS MUST BE USED BY PAIR USING SAME OUTPUT FILE.
       THESE TOOLS ARE SYNCHRONIZABLE.

       The tool is based on power spectrum evaluation through FFT on input and output.

       NRESP2 (default REPEAT) determines the number of sub FFT's used to obtain the results

       .......................
                         ____:_____              _____________
                        |          |    nod_2   |             |
                    +---> module    >----------->             |          output sampled at FSL_2
        ________    |   | under    |            |   resp2_o   |
       |        |   |   | analysis |    norm_2 ->             |
       |(white) |   |   |__________|            |_____________|
       | noise   >--+        :                      |       |
       | source |   |        :......................|.......|.............
       |________|   |                            ___|_______|_           :
                    |                   nod_1   |             |          :
                    +--------------------------->             |          :
                                                |   resp2_i   |          :
                                        norm_1 ->             |          :
                                                |_____________|          :
                                                    |       |            :
                                                  <num>   <bandwidth>    :
        input sampled at FSL_1                            <fmin..fmax>   :
                                                                         :
                                                                         :
                                                                  SEGMENT BOUNDARY

     Principle of operations:

     Tool 'resp2_i samples data of the input, tool 'resp2_o' samples data of the output, each of them at their respective rates
     and phases. The output file name is used by these tools to link themselves together during processes of 'check' and 'init'.
     This link allows the synchronization of the operations of both tools together and the usual synchronization with the other
     synchronizable tools of the simulation. From the data concerning their segments (local sampling frequency and offset), and
     from the tool parameters (number of points), the size of a dual table is computed. This table is filled with zeroes during
     the reset phases. During accumulation, tools are filling their table at their own rate. Filling of the tables is synchronous.

     It is possible to place tool 'resp2_o' before or after tool 'resp2_i'.

     In the example here below, the noise source has been replaced by a regular sequence to show how the data are sampled in the
     dual table:

         ..
         node    x iuser sequence        10  17     up
         node void itool resp2_i "file.out" x 1.0   1000

         decimate 5  3          // decimation by 5 with an offset of 3

         node    y copy  x
         node void itool resp2_o "file.out" y 1.0   1000
         ..

         Two tables of 1000 points are allocated, reset to 0.0:
         Table (x)             Table (y)
          10.0                   0.0
          11.0                   0.0
          12.0                   0.0
          13.0                  13.0
          14.0                   0.0
          15.0                   0.0
          16.0                   0.0
          17.0                   0.0
          10.0                  10.0
          11.0                   0.0
          12.0                   0.0
          13.0                   0.0                  |
          14.0                   0.0                  |
          15.0                  15.0                  |
          16.0  <------------    0.0   --------   Last entry
           0.0                   0.0                  |
           0.0                   0.0                  |
           0.0                   0.0                 \ /
           ..                    ..                   .

         When the tables are filled, the transfer function is computed by FFT's.

                    avg[Sx(freq) . Sy*(freq)]      |  Sx is the Fourier Transform of x.
         TF(freq) = -------------------------      |  Sy is the Fourier Transform of y.
                    avg[Sx(freq) . Sx*(freq)]      |  * indicates the complex conjugate.
                                                   |  avg[] is the RMS average value.

         Impulse_response(time) = IFFT(TF).

         Scaling proportional to the relative data rates is then applied (here in this example 5:1).

     More complex sampling schemes are supported, like a combination of decimation(s) and interpolation(s).

            ..
            node    x iuser sequence        10  17     up
            node void itool resp2_i "file.out" x 1.0   500

            interpolate 2           // interpolation by 2
            ..
            decimate    5           // decimation    by 5

            node    y copy  x
            node void itool resp2_o "file.out" y 1.0   500
            ..

      TIPS: Consult the NAPA User's Guide and look on keyword "with", it allows to write more readable simulation files by moving
            itool nodes in another segments still referring to the appropriate segment location.

            The example above may be rewritten, thanks to keyword "with" as:

            ..
            node    x iuser sequence        10  17     up

            interpolate 2           // interpolation by 2
            ..
            decimate    5           // decimation    by 5

            node    y copy  x

            node void itool resp2_i "file.out" x 1.0   500  with x
            node void itool resp2_o "file.out" y 1.0   500
            ..

     IMPORTANT:

     Careless decimation could aliase a large amount of noise. This noise is dithering the coherence and therefore makes the
     computation of the responses less efficient. More RMS averaging is therefore necessary. Use directive NRESP2 (or its default
     value REPEAT) to set-up the number of sub FFT's to average.

     It is therefore IMPORTANT to remember that a clean response here does not imply that the module under test does not
     contain any aliasing problem nor noise problem.

     The synchronization of these tools by pair is built-in and does not rely on the synchronization mechanism monitored by the
     NAPA for the other tools. But the pair of tools interacts like other single tools with the synchronization mechanism of NAPA.

       THIS TOOL IS SYNCHRONIZABLE

     *** RESP2I, RESP2O TOOL OUTPUT **********************************************************************************************

         packet        time   impulse_resp      step_resp

       Directive :   NO_BANNER

       Directive :   NRESP2_NUM_INITIAL          <Integer_Number>

       Directive :   NRESP2                      <Integer_Number>

       Debug mode:   RESP2_LIST
                     RESP2_SAMPLING_DETAIL      [huge output containing all sample points!]
                     RESP2_FS

Documentation in '..\Tool\fft12.hdr'

     NAPA itool defined functions:  "ptf"

      'ptf' computes the POWER transfer function between input and output and the power factor [ 'cos(phi)' ]

       P = (1/2).(V.I) . cos(phi)     presented in dB as   10.log(P)

      The preferred way to estimate the transfer function or the frequency tracking is to apply a WHITE NOISE at the input of the
      netlist under analysis and to ask for a mean of FFTs to smooth the results. (Use directive REPEAT nn for example). But any
      input signal containing a power spread in the bandwidth of interest could be used.

      CAUTION: If input and output are not sampled at the same data rate, use multirate transfer tools! (not implemented fot ptf)

     USAGE:

     node <nout> itool ptf  <"fnam"> <x> <x_norm> <v> <v_norm> <i> <i_norm>                  <num_pnt>
     node <nout> itool ptf  <"fnam"> <x> <x_norm> <v> <v_norm> <i> <i_norm>   <bandwidth>    <num_pnt>
     node <nout> itool ptf  <"fnam"> <x> <x_norm> <v> <v_norm> <i> <i_norm>   <fmin> <fmax>  <num_pnt>
     node <nout> itool ptf  <"fnam"> <x> <x_norm> <v> <v_norm> <i> <i_norm>                  <num_pnt>  (<opt>)
     node <nout> itool ptf  <"fnam"> <x> <x_norm> <v> <v_norm> <i> <i_norm>   <bandwidth>    <num_pnt>  (<opt>)
     node <nout> itool ptf  <"fnam"> <x> <x_norm> <v> <v_norm> <i> <i_norm>   <fmin> <fmax>  <num_pnt>  (<opt>)

     where  <"fnam"> is the pathname of the output file                         @ init
            <x>         is the input node
            <x_norm>    is the reference level for the analysis of <x>
            <v>         is the 1st output node (voltage)
            <v_norm>    is the reference level for the analysis of <v>
            <i>         is the 2nd output node (current)
            <i_norm>    is the reference level for the analysis of <i>
            <fref>      is the reference frequency for tracking                 @ init
            <bandwidth> is the bandwidth                                        @ init
            <fmin>      is the minimum frequency                                @ init
            <fmax>      is the maximum frequency                                @ init
            <num_pnt>   is the number of points to analyze                      @ init
            <nout>      is the number of single tasks already done by the tool

            (<opt>)     (window) or (no_window) for FFT processing, default is  (window)

            export?     these tools handle the full export list defined by user

            Default value for bandwidth is  0 ... Nyquist

      several parameters can be defined by 'directive': WINDOW, NPTF...
      NPTF (default REPEAT) determines the number of sub FFT's used to obtain the results.

                                                fmin..fmax
       ________         __________              bandwidth    num_pnt
      |        |       |          |             _|_____________|_
      |(white) |       |          |    v       |                 |
      | noise  |---+--->          |------------> (voltage)       |
      | source |   |   | module   |    v_norm ->                 |
      |________|   |   | under    |            |                 |
                   |   | analysis |    i       |                 |
                   |   |          |------------> (current)       |
                   |   |          |    i_norm ->                 |
                   |   |__________|            |                 |
                   |                           |                 |
                   |                   x       |         ptf     |
                   +--------------------------->                 |
                                       x_norm ->                 |
                                               |_________________|

     THIS TOOL IS SYNCHRONIZABLE

       Directive :   NO_BANNER

       Directive :   PTF_NUM_INITIAL                                           <Integer_Number>
       Directive :   NPTF                                                      <Integer_Number>

                  avg[Sx(freq) . Sy*(freq)]       |  Sx is the Fourier Transform of x.
       PTF(freq) = -------------------------      |  Sy is the Fourier Transform of y.
                  avg[Sx(freq) . Sx*(freq)]       |  * indicates the complex conjugate.
                                                  |  avg[] is the RMS average value.

     For more details, see for instance:
         The Fundamentals of Signal Analysis, Application Note 243
         Agilent Technologies, Appendix A, pp 63-66

     *** PTF TOOL OUTPUT *********************************************************************************************************

         packet        freq(Hz)  pow(dB)  power_factor
         + export variables if any

Documentation in '..\Tool\fft2.hdr'

     NAPA itool defined functions:  "tsnr",  "icn"

      'tsnr' evaluates the TSNR (total signal to noise ratio) on a specified bandwidth.
      'icn'  evaluates the ICN  (idle channel noise) on a specified bandwidth.

      TIPS:  use itool 'fft' to understand what itool 'tsnr' or itool 'icn' are doing.

      **********************************************
      *****  CAUTION !!!  **************************
      **********************************************

           During 'tsnr' analysis, it is supposed that the signal by the function is larger than any other peak inside
           the frequency interval [fmin.. fmax] (excluding DC neighbourhood).

           It means that a spurious signal can be considered if this parasitic happens to be larger than the real signal,
           or if the real signal is outside the specified bandwidth. It is quite easy but important to detect such a problem
           by comparing the input frequency with the frequency detected by the 'tsnr' tool. Any deviation indicates that
           the signal used is not the signal to analyse.

      **********************************************

     USAGE:

                                          fmin..fmax
                        __________        bandwidth  num_pnt
       __________      |          |             _|____|_
      |          |     | module   |    x       |        |
      | (signal) |-----> under    |------------>        |
      |__________|     | analysis |            |  tsnr  |
                       |__________|    x_norm ->        |               NB: a template can be produced automatically for TSNR plot
                                               |________|                   useful when sweeping input amplitude of the module

     node <no> itool  tsnr   <"fil_nam">  <x> <x_norm>                   <num_pnt>
     node <no> itool  tsnr   <"fil_nam">  <x> <x_norm>  <bandwidth>      <num_pnt>
     node <no> itool  tsnr   <"fil_nam">  <x> <x_norm>  <fmin> <fmax>    <num_pnt>
     node <no> itool  tsnr   <"fil_nam">  <x> <x_norm>                   <num_pnt>  (<opt>)
     node <no> itool  tsnr   <"fil_nam">  <x> <x_norm>  <bandwidth>      <num_pnt>  (<opt>)
     node <no> itool  tsnr   <"fil_nam">  <x> <x_norm>  <fmin> <fmax>    <num_pnt>  (<opt>)

     Where  <"fil_nam"> is the pathname of the output file                      @ init
            <x>         is the node to be analyzed
            <x_norm>    is the reference level for the analysis of <x>
            <bandwidth> is the bandwidth                                        @ init
            <fmin>      is the min frequency of the frequency bandwidth         @ init
            <fmax>      is the max frequency of the frequency bandwidth         @ init
            <num_pnt>   is the number of points to analyze                      @ init
            <no>        is the number of single tasks already done by the tool

            (<opt>)    (psophometric), (audiometric) or (no_filtering),                                   default is no filtering
                       (window)   or (no_window),                                                         default is window
                       (template) or (no_template), used when plotting a tsnr plot function of amplitude, default is no_template

            export?     this tool handles the full export list.

     Default value for bandwidth is  0 ... Nyquist.
     For total signal to noise ratio analysis (TSNR), test signal should be a sinewave (sine with optional offset and phase).

                                          fmin..fmax
                        __________        bandwidth  num_pnt
       __________      |          |             _|____|_
      |          |     | module   |    x       |        |
      | (signal) |-----> under    |------------>        |
      |__________|     | analysis |            |  icn   |
                       |__________|    x_norm ->        |
                                               |________|

     node <no> itool icn     <"fil_nam">  <x> <x_norm>                 <num_pnt>
     node <no> itool icn     <"fil_nam">  <x> <x_norm>  <bandwidth>    <num_pnt>
     node <no> itool icn     <"fil_nam">  <x> <x_norm>  <fmin> <fmax>  <num_pnt>
     node <no> itool icn     <"fil_nam">  <x> <x_norm>                 <num_pnt>  (<opt>)
     node <no> itool icn     <"fil_nam">  <x> <x_norm>  <bandwidth>    <num_pnt>  (<opt>)
     node <no> itool icn     <"fil_nam">  <x> <x_norm>  <fmin> <fmax>  <num_pnt>  (<opt>)

     Where  <"fil_nam"> is the pathname of the output file                      @ init
            <x>         is the node to be analyzed
            <x_norm>    is the reference level for the analysis of <x>
            <bandwidth> is the bandwidth                                        @ init
            <fmin>      is the min frequency of the frequency bandwidth         @ init
            <fmax>      is the max frequency of the frequency bandwidth         @ init
            <num_pnt>   is the number of points to analyze                      @ init
            <no>        is the number of single tasks already done by the tool

            (<opt>)    (psophometric), (audiometric) or (no_filtering),                                  default is no filtering
                       (window) or (no_window),                                                          default is window

            export?     this tool handles the full export list.

     Default value for bandwidth is  0 ... Nyquist.
     For idle channel noise analysis (ICN), test signal should be a DC signal.

     For both tools, 'directive WINDOW   <xxxx>'    to use windowing function <xxxx>.
     Consult the list of available windowing functions in file "./Resource/winname.hdr"
     Take care that windowing may introduce artefacts in the computation (e.g. a modification of the DC level).
     Debug mode WINDOWING_INFO provides information on the windowing function.

     RMS average of FFT's is possible, but absolutely not recommended, as it it is lowering the computed noise floor,
     en is therefore giving too optimistic values !!!
     Use respectively directives 'NTSNR', 'NICN'. Their common default value is the value of the directive 'REPEAT'
     which has itself a default value of 1.

     THESE TOOLS ARE SYNCHRONIZABLE

       Directive :   NO_BANNER

       Directive :   TSNR_NUM_INITIAL          <Integer_Number>
       Directive :   TSNR_NTICKS               <Integer_Number>     (provides some control on template)
       Directive :   NTSNR                     <Integer_Number>

       Directive :   ICN_NUM_INITIAL           <Integer_Number>
       Directive :   NICN                      <Integer_Number>

     >>>>> CAUTION

     The FFT algorithm is able to handle ANY numbers of samples.

     BUT  - power of 2 is recommended (the fastest)
          - FFT of multiple of small prime numbers are fast
          - But larger the prime numbers, slower the FFT!

     THUS if you notice that simulation is abnormally slow, check the number of data !!!

     *** TSNR TOOL OUTPUT ********************************************************************************************************

         packet        freq(Hz)   sig_RMS(dB)  noise_RMS(dB)   tsnr(dB)
         + export variables if any

     *** ICN TOOL OUTPUT *********************************************************************************************************

         packet        freq(Hz)    icn(dB)    all_power(dB)
         + export variables if any

Documentation in '..\Tool\fft3.hdr'

     NAPA itool defined functions:  "tf", "ftrack"

      'tf' computes the transfer function between input and output and the coherence function of these two signals if possible.
      In addition, it computes the slewrate factor (SRF) which is the slewrate at output for a pure input sinewave, 1V peak.
      In a continuous time circuit, its maximum indicates for which frequency the output exhibits its maximum slope.

      The preferred way to estimate the transfer function or the frequency tracking is to apply a WHITE NOISE at the input of the
      netlist under analysis and to ask for a mean of FFTs to smooth the results. (Use directive REPEAT nn for example). But any
      input signal containing a power spread in the bandwidth of interest could be used. Coherence is computed to confirm the
      validity of the results.

      Remember: Transfer function and frequency tracking do not show noise, nor distortion!

      CAUTION: If input and output are not sampled at the same data rate, use multirate transfer tools 'tf2_i', 'tf2_o' !

     USAGE:

     node <no> itool tf     <"fnam"> <x> <x_norm> <y> <y_norm>                      <num_pnt>
     node <no> itool tf     <"fnam"> <x> <x_norm> <y> <y_norm>        <bandwidth>   <num_pnt>
     node <no> itool tf     <"fnam"> <x> <x_norm> <y> <y_norm>        <fmin> <fmax> <num_pnt>
     node <no> itool tf     <"fnam"> <x> <x_norm> <y> <y_norm>                      <num_pnt> (<opt>)
     node <no> itool tf     <"fnam"> <x> <x_norm> <y> <y_norm>        <bandwidth>   <num_pnt> (<opt>)
     node <no> itool tf     <"fnam"> <x> <x_norm> <y> <y_norm>        <fmin> <fmax> <num_pnt> (<opt>)

     node <no> itool ftrack <"fnam"> <x> <x_norm> <y> <y_norm> <fref>               <num_pnt>
     node <no> itool ftrack <"fnam"> <x> <x_norm> <y> <y_norm> <fref> <bandwidth>   <num_pnt>
     node <no> itool ftrack <"fnam"> <x> <x_norm> <y> <y_norm> <fref> <fmin> <fmax> <num_pnt>
     node <no> itool ftrack <"fnam"> <x> <x_norm> <y> <y_norm> <fref>               <num_pnt> (<opt>)
     node <no> itool ftrack <"fnam"> <x> <x_norm> <y> <y_norm> <fref> <bandwidth>   <num_pnt> (<opt>)
     node <no> itool ftrack <"fnam"> <x> <x_norm> <y> <y_norm> <fref> <fmin> <fmax> <num_pnt> (<opt>)

     where  <"fnam"> is the pathname of the output file                         @ init
            <x>         is the input node
            <x_norm>    is the reference level for the analysis of <x>
            <y>         is the output node
            <y_norm>    is the reference level for the analysis of <y>
            <fref>      is the reference frequency for tracking                 @ init
            <bandwidth> is the bandwidth                                        @ init
            <fmin>      is the minimum frequency                                @ init
            <fmax>      is the maximum frequency                                @ init
            <num_pnt>   is the number of points to analyze                      @ init
            <no>        is the number of single tasks already done by the tool

            (<opt>)     (window) or (no_window) for FFT processing, default is  (no_window)

            export?     these tools handle the full export list defined by user

            Default value for bandwidth is  0 ... Nyquist

      several parameters can be defined by 'directive': WINDOW, NTF, NFTRACK...
      NTF and NFTRACK (default REPEAT) determines the number of sub FFT's used to obtain the results.

                                                fmin..fmax
       ________         __________              bandwidth    num_pnt
      |        |       |          |             _|_____________|_
      |(white) |       | module   |    y       |                 |
      | noise  |---+---> under    |------------>                 |
      | source |   |   | analysis |    y_norm ->                 |
      |________|   |   |__________|            |                 |
                   |                           |       tf        |
                   |                   x       |                 |
                   +--------------------------->                 |
                                       x_norm ->                 |
                                               |_________________|

                                                fmin..fmax   fref
       ________         __________              bandwidth     |    num_pnt
      |        |       |          |             _|____________|_____|_
      |(white) |       | module   |    y       |                      |
      | noise  |---+---> under    |------------>                      |
      | source |   |   | analysis |    y_norm ->                      |
      |________|   |   |__________|            |                      |
                   |                           |       ftrack         |
                   |                   x       |                      |
                   +--------------------------->                      |
                                       x_norm ->                      |
                                               |______________________|

     NB: Transfer function and frequency tracking do not show noise nor distortion!

     THESE TOOLS ARE SYNCHRONIZABLE

       Directive :   NO_BANNER

       Directive :   TF_NUM_INITIAL       (resp FTRACK_NUM_INITIAL      )      <Integer_Number>
       Directive :   NTF                  (resp NFTRACK                 )      <Integer_Number>
       Directive :   TF_COMPUTE_COHERENCE (resp FTRACK_COMPUTE_COHERENCE)      <YES or NO>

     NTF (resp NFTRACK) set to 1 or TF_COMPUTE_COHERENCE (resp FTRACK_COMPUTE_COHERENCE) set to NO: coherence will not be computed

                  avg[Sx(freq) . Sy*(freq)]      |    Sx is the Fourier Transform of x.
       TF(freq) = -------------------------      |    Sy is the Fourier Transform of y.
                  avg[Sx(freq) . Sx*(freq)]      |    * indicates the complex conjugate.
                                                 |    avg[] is the RMS average value.

     For more details, see for instance:
         The Fundamentals of Signal Analysis, Application Note 243
         Agilent Technologies, Appendix A, pp 63-66

       SRF(freq) = 2 . pi . freq . mag(freq)     |    SRF is the maximum slope of a sinusoid multiplied by the gain.

     *** TF TOOL OUTPUT **********************************************************************************************************
         packet        freq(Hz)  mag(dB)   arg(degree)     SRF(V/us)
         packet        freq(Hz)  mag(dB)   arg(degree)     SRF(V/us)   coherence
         + export variables if any

     *** FTRACK TOOL OUTPUT ******************************************************************************************************
         packet        freq(Hz)  mag(dB)
         packet        freq(Hz)  mag(dB)   coherence
         + export variables if any

Documentation in '..\Tool\fft4.hdr'

     NAPA itool defined functions:  "resp"

      'resp'     computes the impulse and step response.

      The preferred way to use the method to get these responses is to apply a WHITE NOISE at the input of the netlist under
      analysis and asking for a mean of FFTs to smooth the results. (Use directive REPEAT nn for example). But any input signal
      containing a power spread in the bandwidth of interest could be used.

      It is therefore IMPORTANT to remember that a clean response here does not imply that the module under test does not
      contain any aliasing problem nor noise problem.

      (Do not expect the best accuracy for the step response, as circuit could be not perfectly linear. But this is a great check
       that impulse response is valid!).

     >>> Valid ONLY for 'fairly' linear circuits, do not expect an extreme precision.

      USAGE:

      node <no> itool resp <"fil_nam"> <x> <x_norm> <y> <y_norm> <maxt> <num_pnt>
      node <no> itool resp <"fil_nam"> <x> <x_norm> <y> <y_norm>        <num_pnt>
      node <no> itool resp <"fil_nam"> <x> <x_norm> <y> <y_norm> <maxt> <num_pnt>  (<opt>)
      node <no> itool resp <"fil_nam"> <x> <x_norm> <y> <y_norm>        <num_pnt>  (<opt>)

      where <"fil_nam"> is the pathname of the output file                      @ init
            <x>         is the input node
            <x_norm>    is the reference level for the analysis of <x>
            <y>         is the the output node
            <y_norm>    is the reference level for the analysis of <y>
            <maxt>      is the interval of time to be output (optional)         @ init
            <num_pnt>   is the number of points to analyze                      @ init
            <no>        is the number of single tasks already done by the tool

            (<opt>)     (window) or (no_window) for FFT processing, default is  (window)

            export?     this tool does not handles  export variable

      Several parameters can be defined by 'directive': WINDOW, NRESP, ...
      NRESP (default: REPEAT) determines the number of sub FFT's used to obtain the result

       _________         __________                 num_pnt
      |         |       |          |             ______|_
      | (white) |       | module   |    y       |        |
      | noise   |---+---> under    |------------>        |
      | source  |   |   | analysis |    y_norm ->        |
      |_________|   |   |__________|            |        |
                    |                           |  tool  |
                    |                   x       |        |
                    +--------------------------->        |
                                        x_norm ->        |
                                                |________|

       THIS TOOL IS SYNCHRONIZABLE

       Directive :   NO_BANNER

       Directive :   RESP_NUM_INITIAL          <Integer_Number>
       Directive :   NRESP                     <Integer_Number>

     For more details, see for instance:
         The Fundamentals of Signal Analysis, Application Note 243
         Agilent Technologies, Appendix A, pp 63-66

     *** RESP TOOL OUTPUT ********************************************************************************************************

         packet        time   impulse_resp      step_resp

Documentation in '..\Tool\fft5.hdr'

     NAPA itool defined functions:  "xcorr", "autocorr"

      'xcorr'    computes the cross correlation between input and output.
      'autocorr' computes the autocorrelation of a signal.

      'autocorr' is functionnally equivalent to 'xcorr' of the signal with itself but is more efficient in terms of speed and
      memory allocations.

      The preferred way to use the method to get these correlations is to apply a WHITE NOISE at the input of the netlist under
      analysis and asking for a mean of FFTs to smooth the results. (Use directive REPEAT nn for example). But any input signal
      containing a power spread in the bandwidth of interest could be used.

     >>> Valid ONLY for 'fairly' linear circuits,

      USAGE:

      node <no> itool xcorr    <"fnam"> <x> <x_norm> <y> <y_norm> <maxt> <num_pnt>
      node <no> itool xcorr    <"fnam"> <x> <x_norm> <y> <y_norm>        <num_pnt>
      node <no> itool xcorr    <"fnam"> <x> <x_norm> <y> <y_norm> <maxt> <num_pnt> (<opt>)
      node <no> itool xcorr    <"fnam"> <x> <x_norm> <y> <y_norm>        <num_pnt> (<opt>)

      node <no> itool autocorr <"fnam"> <y> <y_norm> <maxt> <num_pnt>
      node <no> itool autocorr <"fnam"> <y> <y_norm>        <num_pnt>
      node <no> itool autocorr <"fnam"> <y> <y_norm> <maxt> <num_pnt> (<opt>)
      node <no> itool autocorr <"fnam"> <y> <y_norm>        <num_pnt> (<opt>)

      where <"fnam">    is the pathname of the output file                      @ init
            <x>         is the input node
            <x_norm>    is the reference level for the analysis of <x>
            <y>         is the output node
            <y_norm>    is the reference level for the analysis of <y>
            <maxt>      is the interval of time to be analyzed (optional)       @ init
            <num_pnt>   is the number of points to analyze                      @ init
            <no>        is the number of single tasks already done by the tool

            (<opt>)     (window) or (no_window) for FFT processing, default is  (window)

            export?     these tools handle only the first export variable defined by user.

      several parameters can be defined by 'directive': WINDOW, NXCORR, NAUTOCORR,..
      NXCORR, NAUTOCORR determine the number of sub FFT's used to obtain the results.

       _________         __________                 num_pnt
      |         |       |          |             ______|___
      | (white) |       | module   |    y       |          |
      |  noise  |---+---> under    |------------>          |
      |  source |   |   | analysis |    y_norm ->          |
      |_________|   |   |__________|            |          |
                    |                           |  xcorr   |
                    |                   x       |          |
                    +--------------------------->          |
                                        x_norm ->          |
                                                |__________|

       _________         __________                 num_pnt
      |         |       |          |             ______|___
      | (white) |       | module   |    y       |          |
      |  noise  |-------> under    |------------>          |
      |  source |       | analysis |    y_norm -> autocorr |
      |_________|       |__________|            |          |
                                                |__________|

       THESE TOOLS ARE SYNCHRONIZABLE

       Directive :   NO_BANNER

       Directive :   XCORR_NUM_INITIAL         <Integer_Number>
       Directive :   NXCORR                    <Integer_Number>

       Directive :   AUTOCORR_NUM_INITIAL      <Integer_Number>
       Directive :   NAUTOCORR                 <Integer_Number>

     For more details, see for instance:
         The Fundamentals of Signal Analysis, Application Note 243
         Agilent Technologies, Appendix A, pp 63-66

     *** XCORR TOOL OUTPUT *******************************************************************************************************

         packet        time   xcorr
         + first export variable if any

     *** AUTOCORR TOOL OUTPUT ****************************************************************************************************

         packet        time   autocorr
         + first export variable if any

Documentation in '..\Tool\fft6.hdr'

      NAPA associated twin itool defined functions:  "tf2_i", "tf2_o"
                                                     "ftrack2_i", "ftrack2_o"

      'tf2' computes the transfer function between input and output and the coherence function of these two signals if possible.
      In addition, it computes the slewrate factor (SRF) which is the slewrate at output for a pure input sinewave, 1V peak.
      For a continuous time output, its maximum indicates for which frequency it exhibits the maximum slope.

      'ftrack2' performs the same processing but outputs the frequency tracking.

      Pair of functions computes the transfer function between input and output sampled at DIFFERENT rates. It computes also the
      coherence function of these two signals if possible. Module under test should be FAIRLY LINEAR.

      The preferred way to estimate the transfer function is to apply a WHITE NOISE at the input of the netlist under analysis and
      asking for a mean of FFTs to smooth the results. But any input signal containing a power spread in the bandwidth of interest
      could be used. Coherence is computed to confirm the validity of results.

      These tools must be instantiated by PAIR!
          transfer function:   ->   'tf2_i'     picks the input,   'tf2_o'     picks the corresponding output.
          frequency tracking   ->   'ftrack2_i' picks the input,   'ftrack2_o' picks the corresponding output.

      USAGE:

      node  <ni>  itool  tf2_i      <"nam">  <nod_1> <norm_1>                        <num>
      node  <ni>  itool  tf2_i      <"nam">  <nod_1> <norm_1>         <bandwidth>    <num>
      node  <ni>  itool  tf2_i      <"nam">  <nod_1> <norm_1>         <fmin> <fmax>  <num>
      node  <ni>  itool  tf2_i      <"nam">  <nod_1> <norm_1>                        <num> (<opt>)
      node  <ni>  itool  tf2_i      <"nam">  <nod_1> <norm_1>         <bandwidth>    <num> (<opt>)
      node  <ni>  itool  tf2_i      <"nam">  <nod_1> <norm_1>         <fmin> <fmax>  <num> (<opt>)

      node  <no>  itool  tf2_o      <"nam">  <nod_2> <norm_2>                        <num>
      node  <no>  itool  tf2_o      <"nam">  <nod_2> <norm_2>         <bandwidth>    <num>
      node  <no>  itool  tf2_o      <"nam">  <nod_2> <norm_2>         <fmin> <fmax>  <num>
      node  <no>  itool  tf2_o      <"nam">  <nod_2> <norm_2>                        <num> (<opt>)
      node  <no>  itool  tf2_o      <"nam">  <nod_2> <norm_2>         <bandwidth>    <num> (<opt>)
      node  <no>  itool  tf2_o      <"nam">  <nod_2> <norm_2>         <fmin> <fmax>  <num> (<opt>)

      node  <ni>  itool  ftrack2_i  <"nam">  <nod_1> <norm_1>  <fref>                <num>
      node  <ni>  itool  ftrack2_i  <"nam">  <nod_1> <norm_1>  <fref> <bandwidth>    <num>
      node  <ni>  itool  ftrack2_i  <"nam">  <nod_1> <norm_1>  <fref> <fmin> <fmax>  <num>
      node  <ni>  itool  ftrack2_i  <"nam">  <nod_1> <norm_1>  <fref>                <num> (<opt>)
      node  <ni>  itool  ftrack2_i  <"nam">  <nod_1> <norm_1>  <fref> <bandwidth>    <num> (<opt>)
      node  <ni>  itool  ftrack2_i  <"nam">  <nod_1> <norm_1>  <fref> <fmin> <fmax>  <num> (<opt>)
                                                               <fref>
      node  <no>  itool  ftrack2_o  <"nam">  <nod_2> <norm_2>  <fref>                <num>
      node  <no>  itool  ftrack2_o  <"nam">  <nod_2> <norm_2>  <fref> <bandwidth>    <num>
      node  <no>  itool  ftrack2_o  <"nam">  <nod_2> <norm_2>  <fref> <fmin> <fmax>  <num>
      node  <no>  itool  ftrack2_o  <"nam">  <nod_2> <norm_2>  <fref>                <num> (<opt>)
      node  <no>  itool  ftrack2_o  <"nam">  <nod_2> <norm_2>  <fref> <bandwidth>    <num> (<opt>)
      node  <no>  itool  ftrack2_o  <"nam">  <nod_2> <norm_2>  <fref> <fmin> <fmax>  <num> (<opt>)

      Where <"fnam">    is the pathname of the output file                      @ init
            <num>       is the number of points to analyze                      @ init
            <nod_1>     is the input node
            <norm_1>    is the reference level for the analysis of <x>
            <nod_2>     is the output node
            <norm_2>    is the reference level for the analysis of <y>
            <fref>      is the reference frequency for tracking                 @ init
            <bandwidth> is the bandwidth (to be plotted, analyzed...)           @ init
            <fmin>      is the minimum frequency                                @ init
            <fmax>      is the maximum frequency                                @ init
            <ni>        is the number of single tasks already done by the tool sampling input
            <no>        is the number of single tasks already done by the tool sampling output

            (<opt>)     (window) or (no_window) for FFT processing, default is  (window)

            export?     these tools handle the full export list defined by user

            Default value for bandwidth is  0 ... Nyquist

       <filnam> MUST be the same for corresponding twin tools.
       <num>    MUST be the same for corresponding twin tools.
       <bandwitdh> or <fmin> ... <fmax> MUST be the same for corresponding twin tools.

       Due to the complexity of the synchronization mechanism, it is mandatory to base the control of the simulation on variable
       'TOOL_INDEX' and not on the value of the tool output nodes <ni> or <no>.

       Tools 'tf2_i', resp 'ftrack2_i', and 'tf2_o', resp 'ftrack2_o' may be placed in any order in the netlist.

       THESE TOOLS MUST BE USED BY PAIR USING SAME OUTPUT FILE.
       THESE TOOLS ARE SYNCHRONIZABLE.

       The tools are based on power spectrum evaluation through FFT on input and output.

       NTF2, resp NFTRACK2, (default REPEAT) determines the number of sub FFT's used to obtain the results
       NTF2,  resp NFTRACK2, set to 1, or TF2_COMPUTE_COHERENCE, resp FTRACK2_COMPUTE_COHERENCE,  set to NO (default YES):

       SEGMENT BOUNDARY .......................
                                          ____:_____              _____________
                                         |          |    nod_2   |             |
                                     +---> module    >----------->             |          output sampled at FSL_2
                         ________    |   | under    |            |    tf2_o    |
                        |        |   |   | analysis |    norm_2 ->             |
                        |(white) |   |   |__________|            |_____________|
                        | noise   >--+        :                      |       |
                        | source |   |        :......................|.......|.............
                        |________|   |                            ___|_______|_           :
                                     |                   nod_1   |             |          :
                                     +--------------------------->             |          :
                                                                 |    tf2_i    |          :
                                                         norm_1 ->             |          :
                                                                 |_____________|          :
                                                                     |       |            :
                                                                   <num>   <bandwidth>    :
                         input sampled at FSL_1                            <fmin..fmax>   :
                                                                                          :
                                                                                          :
                                                                                   SEGMENT BOUNDARY

       SEGMENT BOUNDARY .......................
                                          ____:_____              ___________________
                                         |          |    nod_2   |                   |
                                     +---> module    >----------->                   |    output sampled at FSL_2
                         ________    |   | under    |            |    ftrack2_o      |
                        |        |   |   | analysis |    norm_2 ->                   |
                        |(white) |   |   |__________|            |___________________|
                        | noise   >--+        :                      |    |       |
                        | source |   |        :......................|....|.......|........
                        |________|   |                            ___|____|_______|__     :
                                     |                   nod_1   |                   |    :
                                     +--------------------------->                   |    :
                                                                 |     ftrack2_i     |    :
                                                         norm_1 ->                   |    :
                                                                 |___________________|    :
                                                                     |    |       |       :
                                                                   <num>  |  <bandwidth>  :
                         input sampled at FSL_1                           |  <fmin..fmax> :
                                                                          |               :
                                                                        <fref>            :
                                                                                          :
                                                                                   SEGMENT BOUNDARY

       Directive :   NO_BANNER

       Directive :   TF2_NUM_INITIAL       (resp FTRACK2_NUM_INITIAL      )      <Integer_Number>
       Directive :   NTF2                  (resp NFTRACK2                 )      <Integer_Number>
       Directive :   TF2_COMPUTE_COHERENCE (resp FTRACK2_COMPUTE_COHERENCE)      <YES or NO>

       Debug mode:   TF2_LIST              (resp FTRACK2_LIST             )
                     TF2_SAMPLING_DETAIL   (resp FTRACK2_SAMPLING_DETAIL  )      [huge output containing all sample points!]
                     TF2_FS                (resp FTRACK2_FS               )

     Principle of operations:

     Tool 'tf2_i', resp 'ftrack2_i', samples data of the input, tool 'tf2_o', resp 'ftrack2_o', samples data of the output, each
     of them at their respective rates and phases. The output file name is used by these tools to link themselves together during
     This link allows the synchronization of the operations of both tools together and the usual synchronization with the other
     the processes of 'check' and 'init'.
     synchronizable tools of the simulation. From the data concerning their segments (local sampling frequency and offset), and
     from the tool parameters (number of points), the size of a dual table is computed. This table is filled with zeroes during
     the reset phases. During accumulation, tools are filling their table at their own rate. Filling of the tables is synchronous.

     In the example here below, the noise source has been replaced by a regular sequence to show how the data are sampled in the
     dual table:

         ..
         node    x iuser sequence        10  17     up
         node void itool tf2_i "file.out" x 1.0   1000

         decimate 5  3          // decimation by 5 with an offset of 3

         node    y copy  x
         node void itool tf2_o "file.out" y 1.0   1000
         ..

         Two tables of 1000 points are allocated, reset to 0.0:

         Table (x)             Table (y)

          10.0                   0.0
          11.0                   0.0
          12.0                   0.0
          13.0                  13.0
          14.0                   0.0
          15.0                   0.0
          16.0                   0.0
          17.0                   0.0
          10.0                  10.0
          11.0                   0.0
          12.0                   0.0
          13.0                   0.0                  |
          14.0                   0.0                  |
          15.0                  15.0                  |
          16.0  <------------    0.0   --------   Last entry
           0.0                   0.0                  |
           0.0                   0.0                  |
           0.0                   0.0                 \ /
           ..                    ..                   .

         When the tables are filled, the transfer function is computed by FFT's.

                    avg[Sx(freq) . Sy*(freq)]      |  Sx is the Fourier Transform of x.
         TF(freq) = -------------------------      |  Sy is the Fourier Transform of y.
                    avg[Sx(freq) . Sx*(freq)]      |  * indicates the complex conjugate.
                                                   |  avg[] is the RMS average value.

         Scaling proportional to the relative data rates is then applied (here 5:1).

         SRF(freq) = 2 . pi . freq . mag(freq)     |    SRF is the maximum slope of a sinusoid multiplied by the gain.

     More complex sampling schemes are supported, like a combination of decimation(s) and interpolation(s).

            ..
            node    x iuser sequence        10  17     up
            node void itool tf2_i "file.out" x 1.0    500

            interpolate 2           // interpolation by 2
            ..
            decimate    5           // decimation    by 5

            node    y copy  x
            node void itool tf2_o "file.out" y 1.0    500
            ..

      TIPS: Consult the NAPA User's Guide and look on keyword "with", it allows to write more readable simulation files by moving
            itool nodes in another segments still referring to the appropriate segment location.

            The example above may be rewritten, thanks to keyword "with" as:

            ..
            node    x  iuser sequence        10  17     up

            interpolate 2           // interpolation by 2
            ..
            decimate    5           // decimation    by 5

            node    y  copy  x

            node void  itool tf2_i "file.out" x 1.0    500   with x
            node void  itool tf2_o "file.out" y 1.0    500
            ..

     IMPORTANT:

     Careless decimation could aliase a large amount of noise. This noise is dithering the coherence and therefore makes the
     computation of the transfer function less efficient. More RMS averaging is therefore necessary. Use directive NTF2 (or its
     default value REPEAT) to set-up the number of sub FFT's to average.

     NB: Transfer function and frequency tracking do not show noise, nor distortion, nor aliasing!

     The synchronization of these tools by pair is built-in and does not rely on the synchronization mechanism monitored by the
     NAPA for the other tools. But the pair of tools interacts like other single tools with the synchronization mechanism of NAPA.

       THESE TOOLS ARE SYNCHRONIZABLE

     *** TF2_I, TF2_O PAIR OF TOOLS OUTPUT ***************************************************************************************

         packet        freq(Hz)    mag(dB)    arg(degree)    SRF(V/us)
         packet        freq(Hz)    mag(DB)    arg(degree)    SRF(V/us)   coherence
         + export variables if any

     *** FTRACK2_I, FTRACK2_O PAIRS OF TOOLS OUTPUT ******************************************************************************

         packet        freq(Hz)    mag(dB)
         packet        freq(Hz)    mag(DB)    coherence
         + export variables if any

Documentation in '..\Tool\fft7.hdr'

     NAPA itool defined functions:  "gdel"

      'gdel'     computes the group delay.

     Use a white signal noise at input. Analysis based on FFT and IFFT.

     >>> Valid ONLY for 'fairly' linear circuits, with 'fairly' linear phase.

      USAGE:

      node <no> itool gdel  <"fil_nam">  <x> <x_norm> <y> <y_norm>  <num_pnt>
      node <no> itool gdel  <"fil_nam">  <x> <x_norm> <y> <y_norm>  <num_pnt>  (<opt>)

      where <"fil_nam"> is the pathname of the output file                          @ init
            <x>         is the input node
            <x_norm>    is the reference level for the analysis of <x>
            <y>         is the the output node
            <y_norm>    is the reference level for the analysis of <y>
            <num_pnt>   is the number of points to analyze                          @ init
            <no>        is the number of single tasks already done by the tool

            (<opt>)     (window) or (no_window) for FFT processing, default is  (window)

            export?     this tool handles the full export list defined by user

      Several parameters can be defined by 'directive': WINDOW, NGDEL, ...
      NGDEL (default: REPEAT) determines the number of sub FFT's used to obtain the result

                        __________                 num_pnt
       ________        |          |             ______|____
      |        |       | module   |    y       |           |
      | signal |---+---> under    |------------>           |
      |________|   |   | analysis |    y_norm ->           |
                   |   |__________|            |           |
                   |                           |   gdel    |
                   |                   x       |           |
                   +--------------------------->           |
                                       x_norm ->           |
                                               |___________|

       THIS TOOL IS SYNCHRONIZABLE

       Directive :   NO_BANNER

       Directive :   GDEL_NUM_INITIAL          <Integer_Number>
       Directive :   NGDEL                     <Integer_Number>

       Debug mode:   GDEL  triggers the output of a debug information table.

     *** GDEL TOOL OUTPUT ********************************************************************************************************

         packet group_delay(s)   fir_length      symmetry
         + export variables if any

Documentation in '..\Tool\fft8.hdr'

     NAPA itool defined functions:  "quinn2"

      'quinn2' estimates the frequency of a signal by FFT, using the second estimator of Barry G. Quinn.

      TIPS:    windowing does not help here, it hurts! No window is applied by default!

      CAUTION: During 'quinn2' analysis, it is supposed that the signal is larger than any other peak inside the frequency
      interval [fmin.. fmax] (excluding DC neighbourhood). It means that an erroneous signal can be considered if a parasitic
      happens to be larger than real signal, or if real signal is outside the specified bandwidth.

     USAGE:

                                          fmin..fmax
                        __________        bandwidth  num_pnt
       __________      |          |             _|____|_
      |          |     | module   |    x       |        |
      | (signal) |-----> under    |------------>        |
      |__________|     | analysis |            | quinn2 |
                       |__________|    x_norm ->        |
                                               |________|

     node <no> itool quinn2  <"fnam">  <x> <x_norm>                 <num_pnt>
     node <no> itool quinn2  <"fnam">  <x> <x_norm>  <bandwidth>    <num_pnt>
     node <no> itool quinn2  <"fnam">  <x> <x_norm>  <fmin> <fmax>  <num_pnt>
     node <no> itool quinn2  <"fnam">  <x> <x_norm>                 <num_pnt> (<opt>)
     node <no> itool quinn2  <"fnam">  <x> <x_norm>  <bandwidth>    <num_pnt> (<opt>)
     node <no> itool quinn2  <"fnam">  <x> <x_norm>  <fmin> <fmax>  <num_pnt> (<opt>)

     Where  <"fil_nam"> is the pathname of the output file                      @ init
            <x>         is the node to be analyzed
            <x_norm>    is the reference level for the analysis of <x>
            <bandwidth> is the bandwidth                                        @ init
            <fmin>      is the min frequency of the frequency bandwidth         @ init
            <fmax>      is the max frequency of the frequency bandwidth         @ init
            <num_pnt>   is the number of points to analyze                      @ init
            <no>        is the number of single tasks already done by the tool

            (<opt>)     (window) or (no_window) for FFT processing, default is (no_window)

            export?     this tool handles the full export list defined by user

            Default value for bandwidth is  0 ... Nyquist

     RMS of frequencies is possible.

     Use directive 'NQUINN2'. Its default value is the value of the directive 'REPEAT' which has itself a default value of 1.

     THIS TOOL IS SYNCHRONIZABLE

       Directive :   NO_BANNER

       Directive :   QUINN2_NUM_INITIAL        <Integer_Number>
       Directive :   NQUINN2                   <Integer_Number>

       Directive :   QUINN2_LIMIT_TO_NYQUIST   <YES | NO>

     CAUTION *********************************************************************************************************************

     The FFT algorithm is able to handle ANY numbers of samples.

     BUT  - power of 2 is recommended (the fastest)
          - FFT of multiple of small prime numbers are fast
          - But larger the prime numbers, slower the FFT!

     THUS if you notice that simulation is abnormally slow, check the number of data !!!

     *** QUINN2 TOOL OUTPUT ******************************************************************************************************

         packet   frequency
         packet   mean_freq(Hz)     sigma(Hz)
         + export variables if any

Documentation in '..\Tool\fft9.hdr'

     NAPA itool defined functions:  "fft_cs"

      'fft_cs'  computes and output the COSINE and SINE FFT on a specified bandwidth.
          [ Cosine Fourier Transform is the real      part of the FFT ]
          [ Sine   Fourier Transform is the imaginary part of the FFT ]

      Module [dB], phase [Degrees] of the FFT are also output.

      TIPS:  use itool 'win' to understand which signal itool 'fft_cs' is processing (file "fft0.hdr")

     USAGE:

                                          fmin..fmax
                        __________        bandwidth  num_pnt
       __________      |          |             _|____|_
      |          |     | module   |    x       |        |
      | (signal) |-----> under    |------------>        |
      |__________|     | analysis |            | fft_cs |
                       |__________|    x_norm ->        |
                                               |________|

     node <no> itool fft_cs    <"fil_nam">  <x> <x_norm>                 <num_pnt>
     node <no> itool fft_cs    <"fil_nam">  <x> <x_norm>  <bandwidth>    <num_pnt>
     node <no> itool fft_cs    <"fil_nam">  <x> <x_norm>  <fmin> <fmax>  <num_pnt>
     node <no> itool fft_cs    <"fil_nam">  <x> <x_norm>                 <num_pnt> (<opt>)
     node <no> itool fft_cs    <"fil_nam">  <x> <x_norm>  <bandwidth>    <num_pnt> (<opt>)
     node <no> itool fft_cs    <"fil_nam">  <x> <x_norm>  <fmin> <fmax>  <num_pnt> (<opt>)

     Where  <"fil_nam"> is the pathname of the output file                      @ init
            <x>         is the node to be analyzed
            <x_norm>    is the reference level for the analysis of <x>
            <bandwidth> is the bandwidth                                        @ init
            <fmin>      is the min frequency of the frequency bandwidth         @ init
            <fmax>      is the max frequency of the frequency bandwidth         @ init
            <num_pnt>   is the number of points to analyze                      @ init
            <no>        is the number of single tasks already done by the tool

            (<opt>)     (window) or (no_window) for FFT processing, default is  (window)

            export?     this tool ignores the export list defined by user

            Default value for bandwidth is  0 ... Nyquist

     Use   'directive WINDOW   <xxxx>'    to use windowing function <xxxx>
     Consult the list of available windowing functions in file "./Resource/winname.hdr"
     Take care that windowing may introduce an error in the computation (e.g. DC level!).

     Debug mode WINDOWING_INFO provides information on the windowing function.

     RMS average of FFT_CS's is *** NOT *** possible!

     FFT_CS's are normalized versus POWER, not peak voltage.

     THESE TOOLS ARE SYNCHRONIZABLE

       Directive :   NO_BANNER

       Directive :   FFT_CS_NUM_INITIAL        <Integer_Number>
       Directive :   FFT_CS_LIMIT_TO_NYQUIST   <YES or NO>                (default is YES)

     CAUTION *********************************************************************************************************************

     The FFT algorithm is able to handle ANY numbers of samples.

     BUT  - power of 2 is recommended (the fastest)
          - FFT of multiple of small prime numbers are fast
          - But larger the prime numbers, slower the FFT!

     THUS if you notice that simulation is abnormally slow, check the number of data !!!

     *** FFT_CS TOOL OUTPUT ******************************************************************************************************

         packet   frequency   Cosine_FFT    Sine_FFT    Module_dB     Phase

Documentation in '..\Tool\gft1.hdr'

     NAPA itool defined function:    "gft"

       This tool computes the Fourier Transform of a signal at ONE frequency using the algorithm of GOERTZEL. The result is
       exactly the same as that given by the FFT algorithm, but is faster because it only computes the desired point of the
       Fourier Transform. (see file 'Resource/goertzel.hdr' for further precisions)

       IT IS INTERESTING TO NOTE THAT THE FREQUENCY COULD BE ANYTHING AND DOES NOT NEED TO COINCIDE TO ONE OF THE FREQUENCY OF THE
       CORRESPONDING FFT BIN !!!

       The number of samples is arbitrary and does not need to be a power of 2.

       It is very important to note that the value given is also affected by the spread of the peaks due to non coherence and
       windowing effects. It is therefore not possible to deduce the voltage corresponding to a peak from this single point. Use
       COHERENT SAMPLING!

       Several parameters can be defined by directives: 'WINDOW', 'NGFT',...
       Debug mode WINDOWING_INFO provides information on the windowing function.

       RMS average of GFT's is possible:

       Use directive 'NGFT'. Its default value is the value of the directive 'REPEAT' which has itself a default value of 1.
       Debug mode WINDOWING_INFO provides information on the windowing function.

      USAGE:   node <no> itool gft <"fil_nam">  <x> <x_norm>  <freq>  <num_pnt>
               node <no> itool gft <"fil_nam">  <x> <x_norm>  <freq>  <num_pnt>  (<opt>)

      where <"fil_nam"> is the pathname of the output file                      @ init
            <x>         is the node to be analyzed
            <x_norm>    is the reference level for the analysis of <x>
            <freq>      is the frequency for which the DFT point is computed
            <num_pnt>   is the number of points to analyze                      @ init
            <no>        is the number of single tasks already done by the tool

            export?     this tool handles the full export list defined by user

            (<opt>)     (window) or (no_window) for GFT processing, default is (window)

                        __________            freq  num_pnt
       __________      |          |             _|__|_
      |          |     | module   |    x       |      |
      | (signal) |-----> under    |------------>      |
      |__________|     | analysis |    x_norm -> tool |
                       |__________|            |      |
                                               |______|

       THIS TOOL IS SYNCHRONIZABLE

       Directive :   NO_BANNER

       Directive :   GFT_NUM_INITIAL           <Integer_Number>
       Directive :   NGFT                      <Integer_Number>

     *** GFT TOOL OUTPUT *********************************************************************************************************

         packet        freq(Hz)    mag(dB)
         + export variables if any

Documentation in '..\Tool\gft2.hdr'

     NAPA itool defined function:      "tfp"

      This tool computes the Transfer function, and the coherence of two channels at one point of the frequency spectrum, using
      the algorithm of GOERTZEL.

       IT IS INTERESTING TO NOTE THAT THE FREQUENCY COULD BE ANYTHING AND DOES NOT NEED TO COINCIDE TO ONE OF THE FREQUENCY OF THE
       CORRESPONDING FFT BIN !!!

      USAGE:

      node <no> itool  tfp  <"fnam">  <x> <xnorm>  <y> <ynorm>  <freq>  <num_pnt>
      node <no> itool  tfp  <"fnam">  <x> <xnorm>  <y> <ynorm>  <freq>  <num_pnt>  (<opt>)

      where <"fnam">    is the pathname of the output file                      @ init
            <x>         is the input node
            <x_norm>    is the reference level for the analysis of <x>
            <y>         is the output node
            <y_norm>    is the reference level for the analysis of <y>
            <freq>      is the frequency for which the tranfer function is computed
            <num_pnt>   is the number of points to analyze                      @ init
            <no>        is the number of single tasks already done by the tool

            (<opt>)     (window) or (no_window) for GFT processing, default is  (no_window)

            export?     this tool handles the full export list defined by user

                        __________             freq  num_pnt
       ________        |          |             _|____|_
      |        |       | module   |     y      |        |
      | signal |---+---> under    |------------>        |
      |________|   |   | analysis |     ynorm ->        |
                   |   |__________|            |        |
                   |                           |  tool  |
                   |                    x      |        |
                   +--------------------------->        |
                                        xnorm ->        |
                                               |________|

       THIS TOOL IS SYNCHRONIZABLE

       Directive :   NO_BANNER

       Directive :   TFP_NUM_INITIAL           <Integer_Number>
       Directive :   NTFP                      <Integer_Number>

       For more details about the Transfer function, see for instance:
       'The Fundamentals of signal Analysis '(Hewlett Packard)' page 54.

     *** TFP TOOL OUTPUT *********************************************************************************************************

         packet        freq(Hz)   mag(dB)   arg(degree)
         packet        freq(Hz)   mag(dB)   arg(degree)    coherence

Documentation in '..\Tool\histo1.hdr'

     NAPA  itool defined functions:  "histoval", "histoslp"

     'histoval' computes the histogram about the values of the signal.
     'histoslp' computes the histogram about the slopes of the values of the signal.

     Histograms are built from values taken during all the simulation, not by batch. Periodic sampling is not necessary!

     USAGE:

                        __________            num_bin
                       |          |             _|____
                       | module   |    x       |      |
                       | under    |------------>      |
                       | analysis |            |      |
                       |__________|      norm -> tool |
                                               |______|

     node <nb> itool histoval <"fil_nam">  <x> <v_norm>                 <num_bin>
     node <nb> itool histoval <"fil_nam">  <x> <v_norm>  <limit>        <num_bin>
     node <nb> itool histoval <"fil_nam">  <x> <v_norm>  <vmin> <vmax>  <num_bin>

     node <nb> itool histoslp <"fil_nam">  <x> <s_norm>                 <num_bin>
     node <nb> itool histoslp <"fil_nam">  <x> <s_norm>  <limit>        <num_bin>
     node <nb> itool histoslp <"fil_nam">  <x> <s_norm>  <smin> <smax>  <num_bin>

      where

        <"fil_nam"> is the pathname of the output file                          @ init
        <x>         is the the node to be analyzed
        <v_norm>    is the level of reference for the analysis of <x>
        <vmin>      is the bin limit low  (default: HISTOVAL_LOW )              @ init
        <vmax>      is the bin limit high (default: HISTOVAL_HIGH)              @ init
        <s_norm>    is the slope of reference for the analysis of <x>
        <smin>      is the bin limit low  (default: HISTOSLP_LOW )              @ init
        <smax>      is the bin limit high (default: HISTOSLP_HIGH)              @ init
        <limit>     is another way to define the limits [-limit, limit]         @ init
        <num_bin>   is the number of bins                                       @ init
        <nb>        is the bin number corresponding to the current input value

        export?     these tools ignore the export list defined by user

      Several parameters can be defined by 'directive':

         HISTOVAL_LOW    (default: -1.0   )
         HISTOVAL_HIGH   (default:  1.0   )
         HISTOSLP_LOW    (default: -1.0e-6)
         HISTOSLP_HIGH   (default:  1.0e-6)

     **** CAUTION ****

     Several histo tools are allowed inside a simulation as soon as they have exactly the SAME NUMBER OF BINS and output
     in the SAME OUTPUT FILE. Optional limits (see default value above) must be also identical.

     **** PLEASE NOTE ****

     Histograms are NORMALIZED three times:

     SINGLE normalization of single signal
            normalization 0:    SIGNAL versus normalization level

     DOUBLE normalization of all histograms
            normalization 1:    HISTOGRAMS versus number of accumulated samples
            normalization 2:    HISTOGRAMS versus width of bins

     Thanks to the double normalization of histograms, it is possible to place this tool in segments running at different rate
     and IT MAKES SENSE to compare the spread and the heigth of their respective histograms (see paragraph below).

     Output node does not return the effective number of points already processed  but the bin number of the current input value.
     It could be used as a trigger. Histograms are output at the very end of the simulation.

     There is no EXPORT variable capability.

       THESE TOOLS ARE NOT SYNCHRONIZABLE,     see also files "histogram.hdr", "w_histogram.hdr" and "histobin.hdr"

       Directive :   NO_BANNER

       Directive :   HISTOVAL_NUM_INITIAL      <Integer_Number>
       Directives:   HISTOVAL_LOW              <Real_Number>           (default: -1.0  )
                     HISTOVAL_HIGH             <Real_Number>           (default:  1.0  )

       Directive :   HISTOSLP_NUM_INITIAL      <Integer_Number>
       Directives:   HISTOSLP_LOW              <Real_Number>           (default: -1.0e6)
                     HISTOSLP_HIGH             <Real_Number>           (default:  1.0e6)

     Within GNUPLOT, plot with histeps to center correctly the histograms bins.

     *** HISTOVAL TOOL OUTPUT ****************************************************************************************************

         xvalue   outname   outname ....

     *** HISTOSLP TOOL OUTPUT ****************************************************************************************************

         xvalue   outname   outname ....

Documentation in '..\Tool\histobin.hdr'

     NAPA  itool defined function:    "histobin"

     'histobin' computes the histogram about the values of a digital signal.

     Histograms are built from values taken during all the simulation, not by batch.
     Periodic sampling is not necessary! First 'interlude' samples are ignored.

     USAGE:

                        __________              num_bin
                       |          |             _|____
                       | module   |        x   |      |
                       | under    |------------>      |
                       | analysis |            | tool |
                       |__________|        1 -->      |
                                               |______|

     node <nb> itool histobin <"fil_nam">  <x>  1
     node <nb> itool histobin <"fil_nam">  <x>  1  <limit>
     node <nb> itool histobin <"fil_nam">  <x>  1  <hmin> <hmax>

     Where:

         <"fil_nam">   is the pathname of the output file                       @ init
         <x>           is the digital node to be analyzed
         1             is the reference level of <x>, always 1                  @ init
         <hmin>        is the bin limit low                                     @ init
         <hmax>        is the bin limit high                                    @ init
         <limit>       is another way to specify limits [-limit, limit]         @ init

         export?       this tool ignores the export list defined by user

         PLEASE NOTE that for homogeneity with other tools, signal normalization is mandatory.
         Only normalization to 1 is authorized here.

     CAUTION !!!

     Several histobin tools are allowed inside a simulation as soon as they have exactly the SAME NUMBER OF BINS and output
     in the SAME OUTPUT FILE.

     Output node does not return the effective number of points already processed but the bin number of the current input value.

     Histograms are output at the very end of the simulation.
     There is no EXPORT variable capability.

     Due to normalization (see below), it is possible to place this tool in different segments running at different rate
     and IT STILL MAKES SENSE to compare their respective histograms.

     This tool is NOT synchronizable    <<<<<<<<

       Directive:    NO_BANNER
       Directive:    HISTOBIN_NUM_INITIAL      <Integer_Number>

       Directives:   HISTOBIN_LOW              <Integer_Number>          (default: -128)
                     HISTOBIN_HIGH             <Integer_Number>          (default:  127)

     Within GNUPLOT, plot with histeps to center correctly the histograms bins !!!!

     *** HISTOBIN TOOL OUTPUT ****************************************************************************************************

         xvalue   outname   outname ....

     HISTOGRAMS are normalized versus number of accumulated samples

Documentation in '..\Tool\histogram.hdr'

     NAPA itool defined function:    "histogram"

      with an output for an Inverse Normal Probability Plot
                        (output "invnorm", see file "../Resource/invnorm.hdr")

      USAGE:

      node <no> itool histogram  <"fil_nam">  <x> <x_norm>               <num_pnt>  (<opt1>) (<opt2>) (<opt3>)  (<opt4>)
      node <no> itool histogram  <"fil_nam">  <x> <x_norm>  <bin_width>  <num_pnt>  (<opt1>) (<opt2>) (<opt3>)  (<opt4>)

      where <"fil_nam"> is the pathname of the output file                                       @ init
            <x>         is the node to be analyzed
            <x_norm>    is the reference level for the analysis of <x>
            <bin_width> is the width of a histogram bin                         (default is automatic estimation)
            <num_pnt>   is the number of points to collect                                       @ init
            <no>        is the number of single tasks already done by the tool

            (<opt1>)    (scott)                                                 (default)        @ init
                        (sturges)
                        (simple)
                                     method to choose the best bin width

            (<opt2>)    (no_hires)                                              (default)        @ init
                        (hires)      produces an histogram with a higher x-axis resolution than computed by the binning rule
                                     using the same criteria to establish the binning criteria as (no_hires) option.
                                     With 2 histograms, one without, the other with high resolution option, the second histogram
                                     allows to illustrate the first one by showing finer details. Default is 10x

            (<opt3>)    (normed)                                                (default)        @ init
                        (not_normed) counts samples without the double normalization of the Y-axis.

            (<opt4>)    (invnorm)                                               (default)        @ init
                        (no_invnorm)

            export?     the tool handles the full export list.

                                  num_pnt     bin_width
              __________              _|_______|_
             |          |   x        |           |
             | module   |------------>           |
             | under    |            | histogram |
             | analysis |   x_norm -->           |
             |__________|            |___________|

       THIS TOOL IS SYNCHRONIZABLE,     see also files "w_histogram.hdr", "histo1.hdr" and "histobin.hdr"

       **** PLEASE NOTE ****

       Resulting histograms are NORMALIZED three times:

       SINGLE normalization of single signal
              normalization 0:    SIGNAL versus normalization level

       DOUBLE normalization of all histograms
              normalization 1:    HISTOGRAMS versus number of accumulated samples
              normalization 2:    HISTOGRAMS versus width of bins

       Thanks to the triple normalization, it is possible to instantiate this tool in segments running at different rate
       and IT STILL MAKES SENSE to compare the spread and heigth of their respective histograms.

       There is another bin number determination. It is not implemented here. This is the Freedman-Diaconis bin determination.
       It requests to compute interquartile which is awfully long for large number of data!

       **** IMPORTANT TIPS ****

       Within GNUPLOT, plot with histeps to center correctly the histograms bins.
       For linearity analysis with the histogram method, it is important to use a COHERENT triangle at input.

       **** How to handle the Inverse Normal Probability Plot?  There is a Gnuplot profile prepared for this operation:
            (the inverse normal probality plot shows a straight line when the data are normally distributed)

       EXAMPLE where Gnuplot file 'sample.plt' is plotting the 'invnorm data' produced by this tool

            gnuplot> load "invnorm.plt"            (this file is automatically produced by this tool 'histogram').
            gnuplot> load "sample.plt"

       Directive:    NO_BANNER
       Directive:    HISTOGRAM_HIRES          <Real_Number>       defines the resolution multiplication factor with option (hires)
       Directive:    HISTOGRAM_NUM_INITIAL    <Integer_Number>

       Debug mode:   HISTOGRAM

     *** HISTOGRAM TOOL OUTPUT ***************************************************************************************************

         packet   value     histogram      cumul       invnorm
         + export variables if any

Documentation in '..\Tool\history.hdr'

     NAPA  itool defined function:    "history"

     'history' records the last N samples of a signal before simulation ends.

     'history' is built from values taken during all the simulation, not by batch.
     'history' is storing 'long double' to store I_TYPE 'long long' (and of course R_TYPE 'double') without any loss of precision.

     USAGE:

                        __________               num
                       |          |             __|___
                       | module   |      x     |      |
                       | under    |------------>      |
                       | analysis |      norm  | tool |
                       |__________|     ------->      |
                                               |______|

     node <fl> itool history <"filnam">  <x> <norm>  <num>

      where <"filnam"> is the pathname of the output file                       @ init
            <x>        is the node to be analyzed
            <norm>     is the norm of <x>
            <num>      is the number of the last samples to record              @ init
            <fl>       is a flag indicating when ready to output the 'num' points

            export?    this tool ignores the export list defined by user.

     Software implementation: continuous storage in a rolling table.
               _____________
              |             |
            0 |             |
              |_____________|
              |             |
            1 |             |
              |_____________|
              |             |
              :             :
              |_____________|
              |             |          :
          c-1 | newest_data |          :
              |_____________|          :
              |             |
            c | oldest_data |<--- rolling_index ---.
              |_____________|                       \
              |             |          :             \
              :             :         \ /             \
              |_____________|          .               \
              |             |                           \
        num-1 |             |                            \____ in
              |_____________|

     CAUTION !!!

     Several history tools are allowed inside a simulation as soon as they have exactly the SAME NUMBER OF SAMPLES, output in the
     SAME OUTPUT FILE and are computed with the SAME SAMPLING CONDITIONS (e.g. placed in the same segment).

     Output tool does not return the effective number of points already processed but 0 if less then 'num' samples' have been
     already accumulated, 1 otherwise.

     History is output at the very end of the simulation.
     There is no EXPORT variable capability.

     This tool is NOT synchronizable.

       Directive:    NO_BANNER, NO_TIME_OUTPUT

       Debug mode:   HISTORY

     *** HISTORY TOOL OUTPUT *****************************************************************************************************

         outname ...
         time(s)       outname ...

Documentation in '..\Tool\jitter.hdr'

     NAPA itool user defined function:  "jitter"     (time domain analysis)

     'jitter' analyzes a waveform by detecting crossing of a signal level and computes the period and transition jitters
     of one signal referring to itself, or these jitters relative to a reference signal.
     Crossing times are computed through linear interpolation.

     Please note that jitter's computation may fail if noise level or distorsion are too important.

              __________             num_pnt                    __________                  num_pnt
             |          |             __|_____                 |          |                  __|_____
             | module   |     x      |        |                | module   |           x     |        |
             | under    |------------>        |                | under    |----------------->        |
             | analysis |            | jitter |                | analysis |                 |        |
             |__________|     level ->        |                |__________|          level ->        |
                                     |________|                                             | jitter |
                                                                      relative to    xr     |        |
                                                                                     ------->        |
                transition jitter:   'jitter_t'                                             |        |
                period jitter:       'jitter_p'                                     levelr ->        |
                                                                                            |________|

     USAGE:

      node <nout>  itool  jitter  <"fil_nam">  <x> <TRESHOLD>                    <num_pnt>  (option)
      node <nout>  itool  jitter  <"fil_nam">  <x> <TRESHOLD>  <xr> <TRESHOLDr>  <num_pnt>  (option)

      Where <"fil_nam">               the pathname of the output file.                         @ init
            <x>                       the node under test.
            <xr>                      the node of reference if any.
            <TRESHOLD>, <TRESHOLDr>   the THRESHOLD level(s) defining transitions.
            <num_pnt>                 is the number of points to analyze.
            <nout>                    is the number of single tasks already done by the tool.
            (option)                  analyzing (positive), (negative) transitions.            Default is (positive).

            export?     this tool handles the full export list defined by user.

      NB:   The average frequency of the reference should be the same as the average frequency of the signal under test!

            |                       x2
            |                  *    |
            |      signal  *        |
            |           *           |
            |         *             |
        ----t1-------o--------------t2----       <---  treshold level
            |       *               |
            |     *                 |
            |  *                    |
            x1                      |

      Debug:     JITTER

      Directives JITTER_DECISION_LEVEL determines the sensitivity ot the detection of the crossing. Default is EPSILON
                 JITTER_FREQUENCY_COMPARISON sets the warning level of frequencies discrepancies.   Default is 0.001
                 JITTER_NUM_INITIAL    <Integer Number>                                             Default is 0.0
                 NO_BANNER

      Reference, for instance:  https://en.wikipedia.org/wiki/Jitter

     *** JITTER TOOL OUTPUT ******************************************************************************************************

        packet  #period   jitter_t(s) jitter_t(%)   jitter_p(s) jitter_p(%)   transition(s)   period(s)
        + export variables if any

     THIS TOOL IS SYNCHRONIZABLE

Documentation in '..\Tool\lag0.hdr'

     NAPA itool defined function:  "lag"

       To produce data for a LAG PLOT
       Output of this analysis is simply a sequence of couples  x[n], x[n+delay] 

       Lag plots are used to check if a data set or time series is random. Random data should not exhibit any structure
       in the lag plot. Non-random structure implies that the underlying data are not random.

     USAGE:
                        __________            delay   num_pnt
       __________      |          |             _|_____|_
      |          |     | module   |    x       |         |
      | (signal) |-----> under    |------------>         |
      |__________|     | analysis |            |   lag   |
                       |__________|    x_norm ->         |
                                               |_________|

     node <nout> itool lag   <"fil_nam">  <x> <x_norm>           <num_pnt>
     node <nout> itool lag   <"fil_nam">  <x> <x_norm>  <delay>  <num_pnt>

     Where  <"fil_nam"> is the pathname of the output file                      @ init
            <x>         is the node to be analyzed
            <x_norm>    is the reference level for the analysis of <x>
            <delay>     is the delay between two comparison points (default 1)  @ init
                        a delay of 'n' is corresponding to 'n' local clock periods
            <num_pnt>   is the number of points to analyze                      @ init
            <nout>      is the number of single tasks already done by the tool

            export?     this tool handles only the first export variable defined by user

     THIS TOOL IS SYNCHRONIZABLE

       Directive:    NO_BANNER
       Directive:    LAG0_NUM_INITIAL      <Integer_Number>

     *** LAG TOOL OUTPUT *********************************************************************************************************

         packet          x0         xn
         + first export variable if any

Documentation in '..\Tool\lin.hdr'

     NAPA itool defined functions:    "lin", "tdecomp"

      'lin'      evaluates the integral linearity errors (ILE).
      'tdecomp'  decomposes signal in offset, triangle and residues.

      TIPS: use 'tdecomp' to understand what 'lin' is doing

      USAGE:

       ampl frq...      __________           frq  num_pnt
       _|_____|_       |          |           _|__|_
      |         |      | module   |  x       |      |
      |Triangle |------> under    |----------> tool |
      |_________|      | analysis |  x_norm ->      |
                       |__________|          |______|

      node <no> itool lin     <"fil_nam">  <x> <x_norm>  <frq>  <num_pnt>
      node <no> itool lin     <"fil_nam">  <x> <x_norm>         <num_pnt>

      node <no> itool tdecomp <"fil_nam">  <x> <x_norm>  <frq>  <num_pnt>
      node <no> itool tdecomp <"fil_nam">  <x> <x_norm>         <num_pnt>

      where <"fil_nam"> is the pathname of the output file                      @ init
            <x>         is the node to be analyzed
            <x_norm>    is the reference level for the analysis of <x>
            <frq>       is the EXACT frequency of the input waveform (optional) @ init
            <num_pnt>   is the number of points to analyze                      @ init
            <no>        is the number of single tasks already made by the tool

      export?    the tool 'lin' handles the full export list defined by user
                 the tool 'tdecomp' handles only the first export variable defined by user

      several parameters can be defined by 'directive': TPERIODS, LIN_WEIGHT ...

      **** As it is important for accuracy to work with coherent frequencies, a warning is issued if this is not respected.

     ANALYSIS IN THE TIME DOMAIN OF A TRIANGULAR WAVEFORM.

     IT IS RECOMMENDED TO USE COHERENT SAMPLING (see header "coherent_freq.hdr")
     GIVE FREQUENCY, IF IT IS KNOWN, TO HAVE A BETTER PRECISION.

     ILE are measured as a FRACTION of the normalization "y_norm" on BOTH slopes of the triangle supposed to be analyzed.

     **** WARNING ****

     Due to the method of analysis, ILE are absolute values not referring to any LSB. ILE is the error computed versus ideal
     slopes and not versus an ideal "staircase". It means that an ideal converter will exhibit an error of 1 LSB (i.e. +/-0.5 LSB)
     when measured by these tools.

      *** IMPORTANT TIPS ***

     It is possible to avoid that clipping deteriorates the curve fitting. Use the windowing functions (use non zero LIN_WEIGHT
     parameter: 1, 2, ...). Default is 0. Curve fitting will ignore the (possibly clipped) peaks of the triangle.
     The weighting function:  cos(2*PI*x) ^(2*LIN_WEIGHT);

     THESE TOOLS ARE SYNCHRONIZABLE

       Directive:    LIN_WEIGHT           <Integer_Number>

       Directive:    TPERIODS             <Integer_Number>

       Directive:    NO_BANNER
       Directives:   LIN_NUM_INITIAL      <Integer_Number>
                     TDECOMP_NUM_INITIAL  <Integer_Number>

       Debug mode:   GAUSS_MATRIX    triggers the output of a debug information table.

     *** LIN TOOL OUTPUT *********************************************************************************************************

         packet        freq(Hz)   offset    amplitude     ILE      DLE
         + export variables if any

     *** TDECOMP TOOL OUTPUT *****************************************************************************************************

         packet   time(s)  signal                    tri[0]   tri[1]    tri[all]    residue
         packet   time(s)  signal  weighted_signal   tri[0]   tri[1]    tri[all]    residue
         + first export variable if any

Documentation in '..\Tool\lsp0.hdr'

     NAPA itool defined functions:  "lspwin"          (for Lomb-Scargle Periodogram)

     USAGE:

                        __________                   num_pnt
       __________      |          |             ______|_
      |          |     | module   |    x       |        |
      | (signal) |-----> under    |------------>        |
      |__________|     | analysis |            | lspwin |
                       |__________|    x_norm ->        |
                                               |________|

     node <no> itool  lspwin  <"fil_nam">  <x> <x_norm>  <num_pnt>

     Where  <"fil_nam"> is the pathname of the output file                      @ init
            <x>         is the node to be analyzed
            <x_norm>    is the reference level for the analysis of <x>
            <num_pnt>   is the number of points to analyze                      @ init
            <no>        is the number of single tasks already done by the tool

            export?     this tool handles only the first export variable defined by user

       Directive  NO_BANNER

       Directive  LSPWIN_OFAC        <Integer_Number>
                  This directive controls the oversampling parameter, default is 1.

       Directive  LSPWIN_NUM_INITIAL <Integer_Number>

     *** LSPWIN TOOL OUTPUT ******************************************************************************************************

         packet   time(s)   unweighted     weighted

         + first export variable if any

     THIS TOOL IS SYNCHRONIZABLE

Documentation in '..\Tool\lsp1.hdr'

     NAPA itool defined functions:  "lsp"              (Lomb-Scargle Periodogram)

      TIPS: use 'lspwin' to understand which signal 'lsp' is processing (see lsp0.hdr).

     USAGE:
                                         fmin..fmax
                        __________       bandwidth    num_pnt
       __________      |          |             _|____|_
      |          |     | module   |    x       |        |
      | (signal) |-----> under    |------------>        |
      |__________|     | analysis |            |  tool  |
                       |__________|    x_norm ->        |
                                               |________|

     node <no> itool lsp   <"fil_nam">  <x> <x_norm>  <bandwidth>    <num_pnt>
     node <no> itool lsp   <"fil_nam">  <x> <x_norm>  <fmin> <fmax>  <num_pnt>

     Where  <"fil_nam"> is the pathname of the output file                      @ init
            <x>         is the node to be analyzed
            <x_norm>    is the reference level for the analysis of <x>
            <bandwidth> is the bandwidth (to be plotted, to be analyzed...)     @ init
            <fmin>      is the min frequency of the bandwidth                   @ init
            <fmax>      is the max frequency of the bandwidth                   @ init
            <num_pnt>   is the number of points to analyze                      @ init
            <no>        is the number of single tasks already done by the tool

            export?     this tool ignores the export list defined by user

       Directives LSP_IFAC  <Integer Number>             Default  1
                  LSP_OFAC  <Integer Number>             Default  1
                            resp. over Nyquist ratio (to look after Nyquist frequency),
                            and   oversampling ratio (to increase output resolution).

       Directive  LSP_NUM_INITIAL   <Integer Number>
       Directive  NO_BANNER

     *** LSP TOOL OUTPUT *********************************************************************************************************

         packet        freq(Hz)      mag(dB)

     If sampling is periodic and LSP_OFAC = 1, results of LSP and FFT are identical.

     This algorithm computes the Fourier Transform for irregular sampling.
     It is of course MUCH SLOWER than the FFT algorithm.

     (LSP_OFAC = 1)      1000 points is OK, 10000 is awfully long!

     Please note: LSP's are normalized versus sinewave POWER, not sinewave peak

     THIS TOOL IS SYNCHRONIZABLE

Documentation in '..\Tool\output.hdr'

     NAPA itool defined function:  "output"

      'output'     time output of 1 to 5 signals

      USAGE:

                                           num
              _________                _____|____
             |         |       x      |          |
             | module  |-------------->          |
             | under   |              |  output  |        1 output
             | process |       xnorm ->          |
             |_________|              |__________|

                                                          ...
                                           num
              _________                _____|____
             |         |      x0      |          |
             |         |-------------->          |
             |         |              |          |
             |         |      x0norm ->          |
             |         |              |          |
             |         |      x1      |          |
             |         |-------------->          |
             |         |              |          |
             |         |      x1norm ->          |
             |         |              |          |
             |         |      x2      |          |
             |         |-------------->          |
             | module  |              |          |
             | under   |      x2norm ->  output  |        5 outputs
             | process |              |          |
             |         |      x3      |          |
             |         |-------------->          |
             |         |              |          |
             |         |      x3norm ->          |
             |         |              |          |
             |         |      x4      |          |
             |         |-------------->          |
             |         |              |          |
             |         |      x4norm ->          |
             |_________|              |__________|

      node <nout>  itool  output  <"fnam">  <x0> <x0norm>                                                         <num> (<opt>)
      node <nout>  itool  output  <"fnam">  <x0> <x0norm> <x1> <x1norm>                                           <num> (<opt>)
      node <nout>  itool  output  <"fnam">  <x0> <x0norm> <x1> <x1norm> <x2> <x2norm>                             <num> (<opt>)
      node <nout>  itool  output  <"fnam">  <x0> <x0norm> <x1> <x1norm> <x2> <x2norm> <x3> <x3norm>               <num> (<opt>)
      node <nout>  itool  output  <"fnam">  <x0> <x0norm> <x1> <x1norm> <x2> <x2norm> <x3> <x3norm> <x4> <x4norm> <num> (<opt>)

      where <"fnam">       is the pathname of the output file                             @ init
            <xi>, <xinorm> are resp. a node to be processed and its reference level
            <num>          is the number of points to output                              @ init
            <nout>         is the number of single tasks already done by the tool

            (<opt>)     (absolute)  absolute time                                         (default)
                        (relative)  relative time for each packet of data

            export?     this tool does not handle export list

     THIS TOOL IS SYNCHRONIZABLE

       Directive  NO_BANNER
       Directive  OUTPUT_NUM_INITIAL   <Integer Number>

     *** OUTPUT TOOL OUTPUT ******************************************************************************************************

         packet  time(s)           x0name
         packet  relative_time(s)  x0name

         packet  time(s)           x0name x1name
         packet  relative_time(s)  x0name x1name

         packet  time(s)           x0name x1name x2name
         packet  relative_time(s)  x0name x1name x2name

         packet  time(s)           x0name x1name x2name
         packet  relative_time(s)  x0name x1name x2name

         packet  time(s)           x0name x1name x2name x3name
         packet  relative_time(s)  x0name x1name x2name x3name

         packet  time(s)           x0name x1name x2name x3name x4name
         packet  relative_time(s)  x0name x1name x2name x3name x4name

Documentation in '..\Tool\pdetect.hdr'

     NAPA  itool defined functions:  "pdetect"

     'pdetect' detects periodicity in a sequence of numbers
     Regular sampling is not necessary.

     USAGE:                                       length
                        __________              ____:____
                       |          |    x       |         |
                       | module   |------------>         |--> wd
                       | under    |            | pdetect |
                       | analysis |      norm ->         |
                       |__________|            |_________|

     node <wd> itool  pdetect  <"fil_nam">  <x> <norm>
     node <wd> itool  pdetect  <"fil_nam">  <x> <norm>  <length>

     where
        <"fil_nam"> is the pathname of the output file                          @ init
        <x>         is the the node to be analyzed
        <norm>      is the level of reference for the analysis of <x>
        <length>    is the length of the pattern to be analysed                 @init   (default: PDETECT)
        <wd>        is true when a periodicity is detected

     A parameter can be defined by 'directive':

         PDETECT (default: 10)  the length of the pattern to match.

         There is no EXPORT variable capability.

     This tool is NOT synchronizable  <<<<<<<<

       Directive  NO_BANNER
       Directive  PDETECT_NUM_INITIAL   <Integer Number>

     *** PDETECT TOOL OUTPUT *****************************************************************************************************

         time     loop_index    value    norm

Documentation in '..\Tool\process.hdr'

     Example of NAPA itool defined function:  "process"  used in conjunction with itool "collect" .

        **** EXAMPLE **** of process of the data collected by itool 'collect' *****
        **** In this EXAMPLE, output is printed by batch                      *****

     node   <tag>  itool  collect  ...
     node   <no>   itool  process  <"fil_nam">  <tag>

     Where  <"fil_nam"> is the pathname of the output file                      @ init
            <tag>   is the tag assigned to the data array by the tool 'collect'
            <no>    is the number of single tasks already done by the tool

     Example:

          node  tag1  itool  collect   x  1.0            100000
          node  tag2  itool  collect   x  1.0             30000   (time)
          node  tag3  itool  collect   x  1.0  y  1024   250000
          node  tag4  itool  collect   x  1.0  y  1024   100000   (time)

          tool  process  "myfile_1.out"  tag1
          tool  process  "myfile_2.out"  tag4
          ...
          tool  process  "myfile_n.out"  tag2

     Directive  NO_BANNER

Documentation in '..\Tool\rms1.hdr'

     NAPA itool defined function:    "rms"

      This tool computes the RMS value of a signal      SQRT(sum of squares/number of samples)

      USAGE:

      node <no> itool rms  <"fil_nam">  <x> <x_norm>   <tper>

      where <"fil_nam"> is the pathname of the output file                      @ init
            <x>         is the node to be analyzed
            <x_norm>    is the reference level for the analysis of <x>
            <tper>      is the time period to accumulate RMS                    @ init
            <no>        is the number of single tasks already done by the tool

      export?           this tool handles the full export list defined by user

                                              tper
              __________              _________|_
             |          |   x        |           |
             | module   |------------>           |
             | under    |            |    rms    |
             | analysis |   x_norm -->           |
             |__________|            |___________|

       THIS TOOL IS SYNCHRONIZABLE

       Directive  RMS_NUM_INITIAL   <Integer Number>

     *** RMS TOOL OUTPUT *********************************************************************************************************

         packet   rms_value     time_start(s)    time_stop(s)
         + export variables if any

Documentation in '..\Tool\spy.hdr'

     NAPA  itool defined function:  "spy"
     this tool documents on screen the progression of the simulation.

     USAGE:
       node  <nb> itool  spy
       node  <nb> itool  spy  <interval>

     where

        <interval>  is the number of loops between the output on screen                      (default  1)         @ init
        <nb>        is a number corresponding to the number of intervals already on screen

     Only one instantiation of this tool is allowed. This tool is not synchronizable.

     EXAMPLE:

         tool spy  5000

         On screen:
                       ####  Loop        5 000     after          S12.523
                       ####  Loop       10 000     after          S26.194
                       ####  Loop       15 000     after          S43.758
                       ####  Loop       20 000     after          S58.362
                       ####  Loop       25 000     after      M01:S12.889
                       ####  Loop       30 000     after      M01:S27.677
                       ####  Loop       35 000     after      M01:S42.417
                       ####  Loop       40 000     after      M01:S58.751
                       ####  Loop       45 000     after      M02:S22.518
                       ####  Loop       50 000     after      M02:S42.077
                       ####  Loop       55 000     after      M03:S08.547
                       ...

Documentation in '..\Tool\stat1.hdr'

     Simple descriptive statistics    (signal under test is supposed with a normal probability distribution)

     NAPA itool defined functions:  "statval", "statslp"

     'statval' computes the statistics about the values of the signal
     'statslp' computes the statistics about the slopes of the values of the signal

                        __________            num_pnt
                       |          |             _|____
                       | module   |    x       |      |
                       | under    |------------>      |
                       | analysis |            | tool |
                       |__________|    x_norm ->      |
                                               |______|

     USAGE:

      node <no> itool statval <"fil_nam">  <x> <x_norm>  <num_pnt>
      node <no> itool statslp <"fil_nam">  <x> <x_norm>  <num_pnt>

      Where <"fil_nam"> is the pathname of the output file                      @ init
            <x>         is the node to be analyzed
            <x_norm>    is the reference level for the analysis of <x>
            <num_pnt>   is the number of points to analyze
            <no>        is the number of single tasks already done by the tool

            export?     these tools handle the full export list defined by user

      Directives STAT_PRINT_ALL, STAT_PRINT_RATE:

         It is possible to print only final value of the statistics (default) or to print the statistics at each clock period
         (directive 'STAT_PRINT_ALL') at a rate defined by directive STAT_PRINT_RATE (default 1).

      Directive  STAT:

         This directive selects the formula. Possible values are RMS or SIGMA :

         Formula: mean  = Sum[x] / N
                  sigma = (Sum[x^2] - Sum[x]^2 / N) / N             (1)     (RMS)
         or       mean  = Sum[x] / N
                  sigma = (Sum[x^2] - Sum[x]^2 / N) / (N-1)         (2)     (SIGMA)

      Directive  NO_BANNER
      Directives STATVAL_NUM_INITIAL   <Integer Number>
                 STATSLP_NUM_INITIAL   <Integer Number>

     *****************************************************************************************************************************

     Crest Factor (CF)

           CF = MAX(positive_peak - mean, mean - negative_peak) / RMS

               DC               ->  1.0
               Square   Wave    ->  1.0
               Sine     Wave    ->  Sqrt(2.0) = 1.414..
               Triangle Wave    ->  Sqrt(3.0) = 1.732..
               Music has a wide crest factor range typically of 4 .. 10

     Ref: http://en.wikipedia.org/wiki/Crest_factor

     *** STATVAL TOOL OUTPUT *****************************************************************************************************

         packet samples        DC  delta  RMS_no_DC   minimum   maximum   crest_factor
         packet samples      mean  delta  sigma       minimum   maximum   crest_factor
         + export variables if any

     *** STATSLP TOOL OUTPUT *****************************************************************************************************

         packet samples        DC  delta  RMS_no_DC   minimum   maximum
         packet samples      mean  delta  sigma       minimum   maximum
         + export variables if any

     THESE TOOLS ARE SYNCHRONIZABLE

Documentation in '..\Tool\synchro.hdr'

       This tool may complete the NAPA instruction 'interlude' in particular occasions.

       USAGE:   node <no> itool synchro <num>
                node <no> itool synchro <num>  <range>

       Where    <num>    is the number of data this tool must force per packet.    @ init
                <range>  is the range to vary <num> randomly. Default is 1.        @ init
                <no>     is the number of single tasks already done by the tool

                export?    this tool ignores the export list defined by user

       The tool is doing nothing (yes!) but forces other tools to spend at least 'num' periods of clocks to complete the process
       of the 'packet' of data.

       This is also the best way to get a synchronization variable (TOOL_INDEX) in a simulation where no tool is instantiated
       (see "domain.hdr" and "sweep.hdr").

       EXAMPLE 1:

       node void itool fft "fft.out"  s 1.0  1024
       node void itool synchro              10000

         synchro 10000 pts                               synchro 10000 pts
       |-----------------------------------------------|------------------------------
         fft 1024 pts        (wait for synchro)          fft 1024 ppts
       |---------------|...............................|----------------|.............

       EXAMPLE 2:

       ivar ntask   12
       ivar np      ntask * 10

       node void itool fft "fft.out"  s 1.0  1024
       node void itool synchro               1024  np

         synchro 1057 pts               synchro 3193 pts                                         synchro 2088 pts
       |------------------------|------------------------------------------------------------|------------------------
         fft 1024 pts    (wait)    fft 1024 ppts                  (wait)                        fft 1024 ppts
       |---------------|........|----------------|...........................................|----------------|.......

       Use 'directive SYNCHRO_INITIAL' to build other dependencies if needed.

       Example:   directive SYNCHRO_INITIAL  100

       THIS TOOL IS SYNCHRONIZABLE (of course)

Documentation in '..\Tool\w_histogram.hdr'

     NAPA itool defined function:    "w_histogram"

      with an output for Normal Probability Plot           (output "invnorm", see file "../Resource/invnorm.hdr")

      USAGE:

      The idea is to use uniformly distributed variables and their density of probability a weighting factor. It is therefore
      appropriate to analyze the tails of a normal distribution as it will produce better analysis in these areas.

      Take care to generate the correct probability of the occurences of the set of parameters!
      Use functions in parm_rand_uniform(), parm_rand_normal(), parm_rand_rayleigh... to produce the statistical parameters.

      NB: with a weight of 1.0, the results of "w_histogram" are identical to the results of "histogram".

      node <no> itool w_histogram  <"fil_nam">  <x> <x_norm>  <weight>  <bin_width> <num_pnt>
      node <no> itool w_histogram  <"fil_nam">  <x> <x_norm>  <weight>              <num_pnt>
      node <no> itool w_histogram  <"fil_nam">  <x> <x_norm>  <weight>              <num_pnt>  (<opt>)

      where <"fil_nam"> is the pathname of the output file                      @ init
            <x>         is the node to be analyzed
            <x_norm>    is the reference level for the analysis of <x>
            <weight>    is the probability of the occurence of the current set of parameters
            <bin_width> is the WIDTH of a histogram bin                         ( default is automatic estimation)
            <num_pnt>   is the number of points to analyze                      @ init
            <no>        is the number of single tasks already done by the tool

            (<opt>)     method to choose the best bin width,                    @ init
                           (scott)                                              ( default)
                           (sturges)
                           (simple)

            export?     the tool handles the full export list.

                                                           num_pnt   bin_width
              _______________                             ___|_________|___
             |               |                x          |                 |
             |               |--------------------------->                 |
             |  module       |                           |                 |
             |  under        |                x_norm ---->   w_histogram   |
             |  analysis     |                           |                 |
             |               <---+            weight +--->                 |
             |_______________|   |                   |   |_________________|
                                 |set of parms       |
              _______________    |                   |
             |               |   |                   |
             | uniformly     |---+                   |
             | distributed   |                       | probability of occurence of this set of parms
             | parameter(s)  |-----------------------+
             | with a weight |
             |_______________|

       THIS TOOL IS SYNCHRONIZABLE,     see also files "histogram.hdr", "histo1.hdr" and "histobin.hdr"

       **** PLEASE NOTE ****

       Resulting weigthed histograms are NORMALIZED three times:

       SINGLE normalization of single signal
              normalization 0:    SIGNAL versus normalization level

       DOUBLE normalization of all histograms
              normalization 1:    HISTOGRAMS versus number of accumulated samples
              normalization 2:    HISTOGRAMS versus width of bins

       Thanks to the triple normalization, it is possible to instantiate this tool in segments running at different rate
       and IT STILL MAKES SENSE to compare the spread and heigth of their respective histograms.

       There is another bin number determination. It is not implemented here. This is the Freedman-Diaconis bin determination.
       It requests to compute interquartile which is awfully long for large number of data!

       **** IMPORTANT TIPS ****

       Within GNUPLOT, plot with histeps to center correctly the histograms bins.
       For linearity analysis, it is important to use a COHERENT triangle at input.

       **** How to handle the Inverse Normal Probability Plot?  There is a Gnuplot profile prepared for this operation:
            (the inverse normal probality plot shows a straight line when the data are normally distributed)

       EXAMPLE where Gnuplot file 'sample.plt' is plotting the 'invnorm data' produced by this tool

            gnuplot> load "/Simulate/Napados/Hdr/Tool/invnorm.plt"
            gnuplot> load "sample.plt"

       Directive:    NO_BANNER
       Directive:    W_HISTOGRAM_NUM_INITIAL      <Integer_Number>

     *** W_HISTOGRAM TOOL OUTPUT *************************************************************************************************

         packet   value      histogram     cumul      invnorm
         + export variables if any

Documentation in '..\Tool\w_stat.hdr'

     Simple descriptive statistics

     NAPA itool defined functions:  "w_statval"

     'w_statval' computes the statistics about the values of the signal

      The idea is to use uniformly distributed variables and their density of probability a weighting factor. It is therefore
      appropriate to analyze the tails of a normal distribution as it will produce better analysis in these areas.

      Take care to generate the correct probability of the occurences of the set of parameters!
      Use functions in parm_rand_uniform(), parm_rand_normal(), parm_rand_rayleigh... to produce the statistical parameters.

      NB: with a weight of 1.0, the results of "w_statval" are identical to the results of "statval".

                                                          num_pnt
              _______________                             __|_________
             |               |                x          |            |
             |               |--------------------------->            |
             |  module       |                           |            |
             |  under        |                x_norm ---->  w_statval |
             |  analysis     |                           |            |
             |               <---+            weight +--->            |
             |_______________|   |                   |   |____________|
                                 |set of parms       |
              _______________    |                   |
             |               |   |                   |
             | uniformly     |---+                   |
             | distributed   |                       | probability of occurence of this set of parms
             | parameter(s)  |-----------------------+
             | with a weight |
             |_______________|

     USAGE:

      node <no> itool w_statval <"fil_nam">  <x> <x_norm>  <weight>  <num_pnt>

      Where <"fil_nam"> is the pathname of the output file                      @ init
            <x>         is the node to be analyzed
            <x_norm>    is the reference level for the analysis of <x>
            <weight>    is the probability of the occurence of the current set of parameters
            <num_pnt>   is the number of points to analyze
            <no>        is the number of single tasks already done by the tool

            export?     these tools handle the full export list defined by user

      Directives STAT_PRINT_ALL, STAT_PRINT_RATE:

         It is possible to print only final value of the statistics (default) or to print the statistics at each clock period
         (directive 'STAT_PRINT_ALL') at a rate defined by directive STAT_PRINT_RATE (default 1).

      Directive  STAT:

         This directive selects the formula. Possible values are RMS or SIGMA :

         Formula: mean  = Sum[x] / N
                  sigma = (Sum[x^2] - Sum[x]^2 / N) / N             (1)     (RMS)
         or       mean  = Sum[x] / N
                  sigma = (Sum[x^2] - Sum[x]^2 / N) / (N-1)         (2)     (SIGMA)

      Directive  NO_BANNER
      Directive  STATVAL_NUM_INITIAL   <Integer Number>

     *****************************************************************************************************************************

     Crest Factor (CF)

           CF = MAX(positive_peak - mean, mean - negative_peak) / RMS

               DC               ->  1.0
               Square   Wave    ->  1.0
               Sine     Wave    ->  Sqrt(2.0) = 1.414..
               Triangle Wave    ->  Sqrt(3.0) = 1.732..
               Music has a wide crest factor range typically of 4 .. 10

     Ref: http://en.wikipedia.org/wiki/Crest_factor

     *** W_STATVAL TOOL OUTPUT ***************************************************************************************************

         packet samples          DC  delta  RMS_no_DC   minimum   maximum   crest_factor
         packet samples        mean  delta  sigma       minimum   maximum   crest_factor
         + export variables if any

     THIS TOOL IS SYNCHRONIZABLE

NAPA postprocessing functions

Documentation in '..\Post\extrema.hdr'

     NAPA postprocessing function:  "extrema"

     Postprocessing an output file: list of LOCAL min and max

     USAGE:    post extrema  <filenam>              <colnum_y>
               post extrema  <filenam>  <colnum_x>  <colnum_y>
               post extrema  <filenam>              <colnum_y>    (<option>)
               post extrema  <filenam>  <colnum_x>  <colnum_y>    (<option>)

               where  <filenam>  is the pathname of the output file             @ init
                      <colnum_x> is the number (0..) of the x column to process @ init
                      <colnum_y> is the number (0..) of the y column to process @ init

                      (<option>) is   (short)    only extrema points are output
                                      (normal)   1st, last and extrema points are output
                                      (long)     all output points

               default for <column_x> is 0
               default for (<option>) is (normal)

     Example:  post extrema  "file2.out"  0  2  (short)

     >>>>>     ONLY mathematical extrema are detected. It means that 'flat' minimum or maximum are not recorded!

     >>>>>     FILTER THE DATA BEFORE, AS IT IS EXTREMELY SENSITIVE TO ANY LEVEL OF NOISE!

Documentation in '..\Post\eye.hdr'

     NAPA postprocessing function:  "eye"

     Postprocessing a time domain output file: eye diagram

     USAGE:    post eye  <filenam> <colnum> <npts>
               post eye  <filenam> <colnum> <npts>  <delay>

               where  <filenam> is the pathname of the output file              @ init
                      <colnum>  is the number (1..) of the column to process    @ init
                      <npts>    is the number of points per bit (> 10)          @ init
                      <delay>   is the delay to sample   (default 0.0)

     Example:  post eye     "file.out"  2  50   0.2e-6

     Note:     the delay to sample may be computed during the simulation

     directive EYE_NUMBER nnn controls the number of eyes in the diagram. Default is 2.

         EYE DIAGRAM
         ____     _____     ____
             \   /     \   /            EYE_NUMBER must be an integer.
              \ /       \ /
               x         x
              / \       / \
         ____/   \_____/   \____

     Debug mode:    POST    EYE

Documentation in '..\Post\histo2.hdr'

     NAPA postprocessing function:  "histo"

     Postprocessing of an output file: histogram

     USAGE:    post histo <filenam> <colnum>
               post histo <filenam> <colnum>   <limit>
               post histo <filenam> <colnum>   <lo> <hi>
               post histo <filenam> <colnum>   <lo> <hi>  <bin_num>
               post histo <filenam> <colnum>                        (opt)
               post histo <filenam> <colnum>   <limit>              (opt)
               post histo <filenam> <colnum>   <lo> <hi>            (opt)

               where  <filenam> is the pathname of the output file              @ init
                      <colnum>  is the number (1..) of the column to process    @ init
                      <limit>   indicates the limit interval [-limit, +limit]   @ init
                      <lo>      is the lower limit                              @ init
                      <hi>      is the upper limit                              @ init
                      <bin_num> is the NUMBER of bins                           @ init

               (opt)  method to choose the best bin number                      @ init
                           (scott)                                  (default)
                           (sturges)
                           (simple)

     Example:  tool tsnr   "file1.out" a 1.0 4.0e3 100000
               post histo  "file2.out" 5

     Remark:   <limit> and <bin> are computed if values are not given by user

       **** How to handle the Inverse Normal Probability Plot?  There is a Gnuplot file prepared for this operation:
            (the inverse normal probality plot shows a straight line when the data are normally distributed)

       EXAMPLE where Gnuplot file 'sample.plt' is plotting the 'invnorm data' produced by this tool.

       gnuplot> load "_my_profile_invnorm.plt"      (this file is automatically produced by this postprocess function 'histo').
       gnuplot> load "sample.plt"

     *** JITTER TOOL OUTPUT ******************************************************************************************************

      signal_under_analysis  histogram  best_gaussian  cumulative_h  cumulative_g  invnorm_h  invnorm_g

     Debug mode:    POST     HISTO

     Histograms are NORMALIZED two times:

     DOUBLE normalization of all post_histo
            normalization 1:    HISTOGRAMS versus number of accumulated samples
            normalization 2:    HISTOGRAMS versus width of bins

Documentation in '..\Post\join.hdr'

     NAPA postprocessing function:  "join"

     Postprocessing of output files: group files in a single OUTPUT, and DELETE them (by default).

     USAGE:    post  join <filenam>
               post  join <filenam>  (option)

               where  <filenam> is the pathname of the output file                          @ init

                      postprocess using the same output file will produce a single joined file

                      option (force)   disables file compatibility checking                 @ init
                      option (compact) removes blank lines between joined data              @ init
                      option (keep)    do not delete the files which have been joined       @ init

                      >>> an option to one instance applies for all the group of instances

               Option by default is to check file compatibility (identical signal header line)
               >>>>  token '_anything_' in the signal header line may be used to match any token of the other file

     Example:  tool fft   "fft11.out"    a  1.0   50000
               post join  stdout
               tool fft   "fft12.out"    b  1.0  100000
               post join  stdout                    // "fft11.out" and "fft12.out" will be deleted

     Example:  tool fft   "fft11.out"    a  1.0   50000
               post join  "fft_all1.out"  (keep)
               tool fft   "fft12.out"    b  1.0  100000
               post join  "fft_all1.out"  (keep)
               tool fft   "fft21.out"    c  1.0  200000
               post join  "fft_all2.out"  (keep)
               tool fft   "fft13.out"    d  1.0  100000
               post join  "fft_all1.out"  (keep)
               tool fft   "fft22.out"    e  1.0  200000
               post join  "fft_all2.out"  (keep)    // no files will be deleted

     Example:  tool fft   "fft.out"  out norm  bw npts
               post join  stdout
               void <./template_fft.dat>            // add a template, "fft.out" will be deleted
               post join  stdout

     Debug mode:    POST    JOIN

Documentation in '..\Post\prune.hdr'

     NAPA postprocessing function:  "prune"

     POSTPROCESSOR REDUCING THE SIZE OF AN OUTPUT FILE BY REMOVING 0 ORDER REDUNDANCY.
     Process the output file produced by the NAPA instruction 'output'.

     This is useful for instance to get a faster GNUPLOT processing, or before a postprocess to build a SPICE output.

      USAGE:    post prune <filnam">
                post prune <filname>  (keep)

      where     <filnam>         is the pathname of the output file             @ init
                option (keep)    do not delete the file which has been pruned   @ init

      Examples of tool 'prune' instantiation:

      output     "file1.out"   d1  d2
      post       prune "file2.out"

      in "file1.out"

      # current_time                     d1             d2
      0.00000000000000e+000   0.000000e+000  1.000000e+000
      1.00000000000000e-006   1.000000e-002  2.500000e-002
      2.00000000000000e-006   2.000000e-002  5.000000e-002
      3.00000000000000e-006   2.000000e-002  5.000000e-002
      4.00000000000000e-006   2.000000e-002  5.000000e-002
      5.00000000000000e-006   2.000000e-002  5.000000e-002
      6.00000000000000e-006   3.000000e-002  5.000000e-002

      in "file2.out", lines 3 and 4 have been eliminated as they are redundant:

      # current_time                     d1             d2
      0.00000000000000e+000   0.000000e+000  1.000000e+000
      1.00000000000000e-006   1.000000e-002  2.500000e-002
      2.00000000000000e-006   2.000000e-002  5.000000e-002
      5.00000000000000e-006   2.000000e-002  5.000000e-002
      6.00000000000000e-006   3.000000e-002  5.000000e-002

     Debug mode:     POST     PRUNE

Documentation in '..\Post\select.hdr'

     NAPA postprocessing function:  "select"

     Postprocessing of an output file: select lines using the value of a column.

     USAGE:    post select  <filenam>  <colnum>  <lo> <hi>
               post select  <filenam>  <colnum>  <val>
               post select  <filenam>  <colnum>  <lo> <hi>  (<opt1>) (<opt2>) (<opt3>)
               post select  <filenam>  <colnum>  <val>      (<opt1>) (<opt2>) (<opt3>)
               post select  <filenam>  <colnum>             (extern) (<opt2>) (<opt3>)

               where  <filenam> is the pathname of the output file                 @ init
                      <colnum>  is the number (1..) of the column to process       @ init
                      <lo>      is the lower limit of the condition of selection   @ init
                      <hi>      is the upper limit of the condition of selection   @ init
                      <val>     is the value of the condition of selection         @ init
                      (<opt1)   could be (outside)  or (inside)                    (optional)
                      (<opt2)   could be (blank)    or (noblank)                   (optional)
                      (<opt3)   could be (keep)                                    (optional)

               (<inside>)   take data when column value is  INSIDE the limits (included)                   (default)
               (<outside>)  take data when column value is OUTSIDE the limits (excluded)
               (<blank>)    insert one blank line in lieu of deleted consecutive data for plot purpose
               (<noblank>)  do not insert these blank lines                                                (default)
               (<keep>)     do not delete the input file
               (<extern>)   uses an external condition defined by macro SELECT_CRITERION(x) when defined by user in a directive

     Example1:  tool fft      "file1.out"  a  1.0 100000
                post select   "file2.out"  2  900.0 1100.0  (blank)  (inside)
                post select   "file3.out"  2  900.0 1100.0  (outside)

     Example2:  output        "file4.out"  a  b  c  d
                post select   "file5.out"  5                (extern) (noblank)
                directive     SELECT_CRITERION(x)  (ISINTEGER(x/100.0) && (x>0.0))

     Directive        SELECT_CRITERION(x)
     Debug mode:      POST    SELECT

Documentation in '..\Post\sort.hdr'

     NAPA postprocessing function:  "sort"

     Postprocessing of an output file: sort file versus the value of a column.

     USAGE:  post sort  <filenam>
             post sort  <filenam>  <colnum>
             post sort  <filenam>             (<option>)
             post sort  <filenam>  <colnum>   (<option>)

      where <filenam> is the pathname of the output file                                   @ init
            <colnum>  is the number of the column to process (default: 1)                  @ init
                      a positive number [1..[ to count the column number from the left.
           (<option>) (up) or (down)  Default is (up).                                     @ init
                      (keep)          Do not delete the file which have been joined.       @ init

     Example:  node void itool tsnr "file1.out" a 1.0 4.0e3 100000
               post sort     "file2.out"  5                                // sort with comumn #5

     NB: <colnum>, columns  in filename are numbered 1 2 3 ...      (starting with 1)

     Debug mode:     POST   SORT

Documentation in '..\Post\spice.hdr'

     NAPA postprocessing function:  "spice"

     POSTPROCESSOR FOR SPICE COMPATIBLE OUTPUT, TIME DOMAIN PWL SPICE SOURCE

      USAGE:    post spice <"output_filename"> <"format string">

      where     <"output_filename"> is the pathname of the SPICE output file    @ init

                <"format string">   "<signame>[x=<ncol>(S) y=<mcol>(V)]>"       @ init
                                    "<signame>[x=<ncol>(S) y=<mcol>(I)]>"       @ init

                                    or a sequence of these formats enclosed in a single pair of quotes.

                <ncol>              is the column number [1..] of TIME input    @ init
                <mcol>              is the column number [1..] of the output    @ init

      'spice' will convert tabular data produced from a NAPA tool to SPICE Format for simulation with SPICE.

      It is always a good idea to PRUNE the file BEFORE this postprocess to limit the size of the SPICE file (see "prune.hdr").

      Examples of Formats:

                 "DATA1[x=1(S) y=4(V)]"           Voltage Source
                 "SCTR[x=1(S) y=6(I)]"            Current Source

      Respective outputs being for these examples:

                  VDATA1  DATA1  0 PWL ...        a PWL Voltage Source
                  ISCTR   SCTR   0 PWL ...        a PWL Current Source

      One or more signals may be defined in this way, and they will all appear in the same output file. The format string syntax
      is VERY STRICT, and any deviation from the above example with regard to spaces, brackets, etc. will cause an error.

                 "SIGA[x=1(S) y=4(V)] SIGB[x=2(S) y=6(I)]"  ...

      Output being for this example:

                  VSIGA   SIGA   0 PWL ...        a PWL Voltage Source
                  ISIGB   SIGB   0 PWL ...        a PWL Current Source

      3 examples of tool 'spice' instantiations:

      tool   resp  "file1.out"  s1 1.0 1024
      post   spice "file2.spc" "R1[x=1(S) y=3(V)]"

      output "file1.out"   a b c d
      post   spice "file3.spc" "b[x=1(S) y=3(V)] c[x=1(S) y=4(I)]"

      void   "file1.out"
      post   spice "file4.spc" "b[x=1(S) y=3(V)] c[x=1(S) y=4(I)]"

      Debug mode:      POST  SPICE

Documentation in '..\Post\stat2.hdr'

     NAPA postprocessing function:  "stat"

     Postprocessing an output file: statistics (mean, sigma, min, max, cp, cpk..)

     USAGE:    post stat  <filenam> <colnum>
               post stat  <filenam> <colnum>  <LSL> <USL>

               where  <filenam> is the pathname of the output file              @ init
                      <colnum>  is the number (1..) of the column to process    @ init
                      <LSL>     is the limit  low of the spec                   @ init
                      <USL>     is the limit high of the spec                   @ init

     if LSL and USL are supplied, values of cpl, cpu, cp, cpk, bad and yield are computed.

     Example:  tool tsnr  "file1.out"  a 1.0  4.0e3  100000
               post stat  "file2.out"  5

     Debug mode:

        POST   STAT

Documentation in '..\Post\wcpk.hdr'

     NAPA postprocessing function:  "wcpk", "wcpk_pwl"

     Postprocessing an output file: Use the superposition theorem to compute the worst case PEAKS for a LINEAR SYSTEM from the
     list of local minimums and maximums of a valid STEP RESPONSE.

     This procedure is equivalent to the method of the L1 Norm of the impulse response.
     The sign inversion in impulse response corresponds to the extrema in step response.

              "wcpk"          computes the worst case of peak from a step response
              "wcpk_pwl"      builds the 2 activations to get this worst case of peak.

     USAGE:   post wcpk      <filenam>             <colnum_y>
              post wcpk      <filenam>  <colnum_t> <colnum_y>

              post wcpk_pwl  <filenam>             <colnum_y>
              post wcpk_pwl  <filenam>  <colnum_t> <colnum_y>

              where  <filenam>  is the pathname of the output file              @ init
                     <colnum_t> is the number (0..) of the t column 'time'      @ init
                     <colnum_y> is the number (0..) of the y column 'signal'    @ init

              default for <column_t> is 0

     The output of "wcpk_pwl" is a PWL description of the 2 activations to get the worst case output in terms of peaking.

     Example of application:  Sizing analog and digital filters

               CAUTION:  Filters need some time to initialize and to stabilize! It is ABSOLUTELY mandatory that the step function
                         and the postprocessing is applied after complete stabilization of the output.

        ________        ______     ______     ___    _______
       |  step  |  in  | AA   |   |SWC   |   |   |  |digital|
       |function|------|filter|-+-|filter|-+-|ADC|--|filter |-+
       |________|      |______| | |______| | |___|  |_______| |
                                |          |                  |
                                |          |             out4 +-----> postprocess
                                |     out2 +------------------------> postprocess
                           out1 +-----------------------------------> postprocess

     Example:

       ...
       debug  WCPK
       interlude   1000                          // wait for complete stabilization!
       ...
       node   in   step  0.0 2.5  10.0e-3        // use largest expected input dynamic
       node   out1 cell  c1  <filt22.net>    in     "myAA.dat"
       node   out2 cell  c2  <biquad.net>  out1     "myBQ.dat"
       node   out3 ...
       ...
       terminate   TIME >= 50.0e-3               // wait for complete stabilization!
       ...
       output "file1.out"    out1 out2 out3 out4
       ...
       post wcpk      1  "file2.out" 0 1  // postprocess out1 from file "file1.out"
       post wcpk      2  "file3.out" 0 2  // postprocess out2 from file "file1.out"
       post wcpk      3  "file4.out" 0 4  // postprocess out4 from file "file1.out"

       post wcpk_pwl  4  "pwl2.out"  0 1  // postprocess out1 from file "file1.out"
       post wcpk_pwl  5  "pwl3.out"  0 2  // postprocess out2 from file "file1.out"
       post wcpk_pwl  6  "pwl4.out"  0 4  // postprocess out4 from file "file1.out"

     Debug mode:     POST   WCPK

Documentation in '..\Post\wipe.hdr'

     NAPA postprocessing function:  "wipe"

     Postprocessing of an output file:  replace the ones and zeroes in a column.

     USAGE:    post wipe  <filenam>  <colnum>
               post wipe  <filenam>  <colnum>  (extract)

               where  <filenam> is the pathname of the output file               @ init
                      <colnum>  is the number (1..) of the column to process     @ init
                      (extract) to keep only the processed column

               directive  WIPE_REPLACEMENT_FOR_0    (default ' ')  is the replacement character for '0'
               directive  WIPE_REPLACEMENT_FOR_1    (default '1')  is the replacement character for '1'

     EXAMPLE:

      '  1  00000000000000000100000000000000000 9.29 '                          '  1                   1                  9.25 '
      '  2  11111111111111110001111111111111111 5.04 '                          '  2  1111111111111111   1111111111111111 5.04 '
      '  3  00000000000000010100000000000000000 6.34 '                          '  3                 1 1                  6.30 '
      '  4  11111111111111001001111111111111111 2.67 '                          '  4  11111111111111  1  1111111111111111 2.61 '
      '  5  00000000000001000000000000000000000 9.16 '                          '  5               1                      9.10 '
      '  6  11111111111100011111111111111111111 7.17 '                          '  6  111111111111   11111111111111111111 7.12 '
      '  7  00000000000101000000000000000000000 8.52 '    post wipe stderr 2    '  7             1 1                      8.59 '
      '  8  11111111110010011111111111111111111 7.92 '    ------------------>   '  8  1111111111  1  11111111111111111111 7.93 '
      '  9  00000000010000000000000000000000000 8.15 '                          '  9           1                          8.14 '
      ' 10  11111111000111111111111111111111111 5.62 '                          ' 10  11111111   111111111111111111111111 5.69 '
      ' 11  00000001010000000000000000000000000 9.15 '                          ' 11         1 1                          9.11 '
      ' 12  11111100100111111111111111111111111 9.54 '                          ' 12  111111  1  111111111111111111111111 9.59 '
      ' 13  00000100000000000000000000000000000 6.74 '                          ' 13       1                              6.76 '
      ' 14  11110001111111111111111111111111111 6.51 '                          ' 14  1111   1111111111111111111111111111 6.59 '
      ' 15  00010100000000000000000000000000000 6.54 '                          ' 15     1 1                              6.59 '

      '  1  00000000000000000100000000000000000 9.29 '                                  '                  1                   '
      '  2  11111111111111110001111111111111111 5.04 '                                  ' 1111111111111111   1111111111111111  '
      '  3  00000000000000010100000000000000000 6.34 '                                  '                1 1                   '
      '  4  11111111111111001001111111111111111 2.67 '                                  ' 11111111111111  1  1111111111111111  '
      '  5  00000000000001000000000000000000000 9.16 '                                  '              1                       '
      '  6  11111111111100011111111111111111111 7.17 '                                  ' 111111111111   11111111111111111111  '
      '  7  00000000000101000000000000000000000 8.52 '   post wipe stderr 2 (extract)   '            1 1                       '
      '  8  11111111110010011111111111111111111 7.92 '   --------------------------->   ' 1111111111  1  11111111111111111111  '
      '  9  00000000010000000000000000000000000 8.15 '                                  '          1                           '
      ' 10  11111111000111111111111111111111111 5.62 '                                  ' 11111111   111111111111111111111111  '
      ' 11  00000001010000000000000000000000000 9.15 '                                  '        1 1                           '
      ' 12  11111100100111111111111111111111111 9.54 '                                  ' 111111  1  111111111111111111111111  '
      ' 13  00000100000000000000000000000000000 6.74 '                                  '      1                               '
      ' 14  11110001111111111111111111111111111 6.51 '                                  ' 1111   1111111111111111111111111111  '
      ' 15  00010100000000000000000000000000000 6.54 '                                  '    1 1                               '

     Debug mode:     POST   WIPE

Documentation in '..\Post\zip.hdr'

     NAPA postprocessing function:  "zip"

     Zip file with command '7z.exe'.

     PLEASE NOTE: the '7z.exe' and related files should exist on the system. Macro ZIP_COMMAND is used to locate this executable.

     USAGE:    post zip

     Example:  tool fft  "file1.out"  a 1.0  100000
               post zip

          >>>  file "file1.out" is zipped as "file1_out.zip"

     Use directive  ZIP_FORMAT     to choose the type of encoding,                      default is "zip"
     Use directive  ZIP_EXTENSION  to choose the filename extension of the zipped file, default is  ZIP_FORMAT

        Format  >  Filename Extension
        ------     -----------------------------
          "7z"  >  ".7z"
          "xz"  >  ".xz"
         "zip"  >  ".zip"
        "gzip"  >  ".gzip",  ".gz",  ".tgz"
       "bzip2"  >  ".bzip2", ".bz2", ".tbz2", ".tbz"
         "tar"  >  ".tar"
         "wim"  >  ".wim",   ".swm"
        ------     -----------------------------

     Example:  tool fft  "file2.out"  a 1.0  100000
               post zip
               directive ZIP_FORMAT "tar"

          >>>  file "file2.out" is zipped as "file2_out.tar"

     Example:  tool fft  "file3.out"  a 1.0  100000
               post zip
               directive ZIP_FORMAT  "gzip"
               directive ZIP_EXTENSION ".gz"

          >>>  file "file3.out" is zipped as "file3_out.gz"

     Debug mode:    ZIP or POST

NAPA external random generators

Documentation in '..\Random_Generator\jlkiss64.hdr'

     Public domain code for JLKISS64()  RNG - long period KISS RNG producing 64-bit results.

     USAGE:

     To switch off the internal pseudorandom noise generator and replace it by this generator, insert this line in the netlist:

     directive JLKISS64

     In addition to this directive, it is possible to choose a seed randomizer, insert this (optional) line in the netlist:

     directive  SEED_RANDOMIZER_METHOD  <n>

           n = 1   Matsumoto & Nishimura Improved Linear Congruential Generator (default)
           n = 2   Super Duper Linear Congruential Generator
           n = 3   Park & Miller Minimal Standard Generator

     Instruction 'debug PSEUDO_RANDOM_GENERATOR' triggers the output of a debug information
     Additional information is added with directive VERBOSE

Documentation in '..\Random_Generator\mt19937.hdr'

     MT19937 Uniform Random Number Algorithm          - 64 bits -

     This is the actual default generator included in the by default int the simulator, provided here as an example

     USAGE:

     To switch off the internal pseudorandom noise generator and replace it by this generator, insert this line in the netlist:

     directive MT19937

     In addition to this directive, it is possible to choose a seed randomizer, insert this (optional) line in the netlist:

     directive  SEED_RANDOMIZER_METHOD  <n>

           n = 1   Matsumoto & Nishimura Improved Linear Congruential Generator (default)
           n = 2   Super Duper Linear Congruential Generator
           n = 3   Park & Miller Minimal Standard Generator

     Instruction 'debug RANDOM_PSEUDO_GENERATOR' triggers the output of a debug information
     Additional information is added with directive VERBOSE

Documentation in '..\Random_Generator\randomizer.hdr'

     Set of simple auxiliary random generators reserved to create the seeds of longer period pseudo random generators

      - Matsumoto & Nishimura Improved Linear Congruential Generator  (default)
      - Super Duper Linear Congruential Generator
      - Park & Miller Minimal Standard Generator

     Used only in conjunction with the external random noise generators.

Resources used by NAPA headers

Documentation in '..\Resource\alternate.hdr'

     Macro    'ALTERNATE(x, a, b)'
        returns a if x == b,  returns b if x == a,     CAUTION: x MUST BE be initialised to a or b !!!!

     Function 'alternate(x, a, b)'
        returns a if x == b,  returns b if x == a,  returns a otherwise

Documentation in '..\Resource\array.hdr'

     Macros functions ARRAY1_ELEMENTCOUNT(), ARRAY2_LINECOUNT(), ARRAY2_COLUMNCOUNT()

     ARRAY1_ELEMENTCOUNT(arr1)  returns the number of elements of a unidimensional array.
     ARRAY2_ELEMENTCOUNT(arr1)  returns the number of elements of a bidimensional array.

     ARRAY2_COLUMNCOUNT(arr2)   returns the number of columns of a bidimensional array.
     ARRAY2_LINECOUNT(arr2)     returns the number of lines of a bidimensional array.

Documentation in '..\Resource\assert.hdr'

     Advanced User, for debug purpose of user's functions.

Documentation in '..\Resource\audiometric.hdr'

      Audiometric weighting in frequency domain.

       Function audio_estimate(array, sizeofarray, indexmin, indexmax)
       where array is a table of frequencies and linear gain, the gains are weighted with the audio A-weighting standard.

       Reference Audio A-weighting ANSI S1.4A-1985

Documentation in '..\Resource\bairstow.hdr'

     Bairstow's Algorithm extracts the complex roots of polynomials with real coefficients

     coef[0] + coef[1]*x + coef[2]*x^2 + .. + coef[n]*x^n == 0.0

     USAGE:    num_root = bairstow(len, coef*, R*, I*, tag)

        where  long   num_root       output: number of roots of polynomial equation
               long   len            input : number of coefficients (n+1)
               double coef[]         input : coefficients of the polynomial (0 to n)
               double R[]            output: will contain the real part      of the root
               double I[]            output: will contain the imaginary part of the root
               char  *tag            input : tag used to output an error message if any

     All polynomial root finders have problems maintaining accuracy in the presence of repeated roots. This is no exception!
     Using long double in internal computations brings only a marginal help.

Documentation in '..\Resource\barker.hdr'

     Barker Codes, which are subsets of PN sequences, are commonly used for frame synchronization in digital communication systems.

     Barker Codes have length at most 13 and have low correlation sidelobes.

     A correlation sidelobe is the correlation of a codeword with a time-shifted version of itself.

     Function   p = barker_code(n, m)

     where      n  is in (-13,-11,-7,-5,-4,-3,-2,-1, 1, 2, 3, 4, 5, 7, 11, 13)
                0 < m < abs(n)
                p  is the bipolar output [0,1]

Documentation in '..\Resource\beep.hdr'

     'beep(n)' triggers 'n' ugly beeps

Documentation in '..\Resource\beta.hdr'

     Function 'beta(a,b)'   where a and b are strictly positive

Documentation in '..\Resource\between.hdr'

     Function between(xa,ya, xb,yb, xc,yc) is true if point (xc,yc) is located between points (xa,ya) and (xb,yb).
     The points must be numerically collinear.

Documentation in '..\Resource\biexponential.hdr'

     Biexponential function

      x = biexponential(t, a, b)    with t, a and b >= 0

      The maximum occurs at t = (1/(b-a)) * log(b/a)
      For a == b, the maximum occurs at 1/a

Documentation in '..\Resource\bin2dec.hdr'

      Macro function   bin2dec(bn, .., b2, b1, b0) converts a sequence of bits (0 or 1) in a positive decimal integer.
      The number of arguments <b>... is variable, but strictly smaller than 64

      ****** CAUTION ******: There is NO automatic cast of arguments! Be careful to check input types and CAST constants !!!!!

Documentation in '..\Resource\binomial.hdr'

     Function     binomial(n, k),  returns a double
     see also nCm()

Documentation in '..\Resource\bit.hdr'

     Function 'test_bit(n,m)'  tests the value of the nth bit of long integer m.

      m  =  ...ponmlkjihgfedcba
                              |    LSB is bit #0
            ...################
            ...111111
            ...5432109876543210

     Function 'extract_bits(b, m)'  extracts bits of long integer m and store in array b.
     Bits extracted:  MSB, ... LSB

     Function 'msb_rank(n)'  gives the rank of the most significant bit of n.

Documentation in '..\Resource\bitmask.hdr'

     Macro functions:
        BIT_SET  (target, mask)
        BIT_CLEAR(target, mask)
        BIT_TEST (target, mask)

Documentation in '..\Resource\blank_line.hdr'

     Function 'blank_line(..,false)' introduces a blank line on outputs only at first call. Good to produce nicer documentation.

     Examples:    blank_line(stderr, stdlog, false)
                  blank_line(stdout,   NULL, false)

     Function 'blank_line(.., true)' introduces a blank line on outputs.

     Examples:    blank_line(stderr, stdlog, true)
                  blank_line(stdout,   NULL, true)

Documentation in '..\Resource\bool.hdr'

     Macro   ISBOOL(v)   returns 1 or 0

     Usage     y = ISBOOL(x)

Documentation in '..\Resource\c.hdr'

       This subheader allocates and defines COSINE arrays.
       The idea is to create a minimum of arrays in an efficient way, saving time and memory allocation and optimize reuse of
       tables. Process is transparent for calling function.

       USAGE:   C_MANAGER(ALLOCATE, &costable,  number, tag)
                C_MANAGER(FREE,     &costable,  number, tag)
                C_MANAGER(QUERY,    &costable,  number, tag)

       Returns the number of elements allocated (long integer).

       Where '&costable' is the address of array of double and 'number' is the number of samples in a cosine period. Memory is
       allocated and address is returned back (ALLOCATE), or memory is desallocated and NULL address returned back (FREE).  Size
       of memory allocated can be obtained (QUERY). 'tag' is a string identifying the tool being used.

       Related functions: see also S_MANAGER() and SC_MANAGER()

Documentation in '..\Resource\calc.hdr'

     Macros to create a scientific calculator inside a C function.

     Structure:  CALC_STACK

     USAGE:      CALC_CLSTK(my_stack)

                 CALC_PUSH(my_stack, element)
       element = CALC_POP(my_stack)

                 CALC_CHS(my_stack)
                 CALC_SWAP(my_stack)
                 CALC_PLUS(my_stack)
                 CALC_MINUS(my_stack)
                 CALC_TIMES(my_stack)
                 CALC_DIVIDE(my_stack)
                 CALC_ABS(my_stack)
                 CALC_INV(my_stack)
                 CALC_SIN(my_stack)
                 CALC_COS(my_stack)
                 CALC_EXP(my_stack)
                 CALC_LOG(my_stack)
                 CALC_POW(my_stack)

       element = CALC_READX(my_stack)     Stack unchanged
       pointer = CALC_READP(my_stack)     Stack unchanged

                 CALC_INFO(my_stack)      Stack unchanged, debug information on stderr

     'directive CALC_STACK_SIZE nn' adjusts the number of elements of the stack (default 100)

      NB: A structure of type CALC_STACK must be declared

Documentation in '..\Resource\cast.hdr'

      Macro  'CAST(new_type, old_object)'           Cast any object to any type

        Example:

           union 
             char ch[4];
             int  i[2];
            my_union;

           long    longvar;

           longvar = (long) my_union;         <---- ILLEGAL cast
           longvar = CAST(long, my_union);    <----   Legal cast

Documentation in '..\Resource\cgaussian.hdr'

     Function 'cgaussian(x,y,z)'

     USAGE    <r2> = cgaussian(<sigma>, <r1>, <rho>)

              where  <r2> is the generated correlated gaussian variable
                     <r1> is a gaussian random variable
                     <sigma> is the standard deviation
                     <rho> is the correlation factor,  -1 <= rho <= 1

Documentation in '..\Resource\char.hdr'

     Functions 'lower_case(str)',  'upper_case(str)',  'capitalize(str)'

     USAGE:      char *str;
                 char  buf[32] = "Mary had a little lamb";
                 ...
                 str = buf;
                 str = capitalize(str);                                    ->  "Mary Had A Little Lamb"
                 str = lower_case(str);                                    ->  "mary had a little lamb"
                 str = upper_case(str);                                    ->  "MARY HAD A LITTLE LAMB"

     Function 'replace_char(str, c1, c2)'

     USAGE:      char *str;
                 char  buf[32] = "Mary had a little lamb";
                 ...
                 str = buf;
                 str = replace_char(str, 'd', 's');                        ->  "Mary has a little lamb"

Documentation in '..\Resource\check.hdr'

      Macro CHECK(condition, text)

     Advanced User, for debug purpose.

      USAGE:     CHECK(<some_condition>, "<message>")

Documentation in '..\Resource\check_period.hdr'

      This subheader verifyies the periodicity of the local sampling.

Documentation in '..\Resource\chi2.hdr'

      chi2(x, n)

Documentation in '..\Resource\clip.hdr'

     Function 'clip(x, lo, hi)'   returns x in interval (lo, hi)

Documentation in '..\Resource\clipping_line.hdr'

     Cohen-Sutherland Algorithm for line clipping

     USAGE: clipping_line(&x1, &y1, &x2, &y2, xmin, ymin, xmax, ymax)

     where (x1,y1), (x2,y2) are the coordinates of the straight line to be clipped,
           (xmin,ymin), (xmax, ymax) are the diagonal corners of the rectangular viewport which will clip the line.

     the function returns   -1  if the line is degenerated to a single point,
                             0  if the line is totally clipped,
                         and 1  otherwise.

Documentation in '..\Resource\clock.hdr'

     Functions 'clock_id()', 'clock_reset()', 'clock_time()', clock_print()'

      this file uses CLOCKS_PER_SEC defined in C library "time.hdr"
      these wall clock functions are independent of the clock WALLCLOCK defined in the NAPA simulator.

      this function requests the management of an ID number,
      this ID number (long integer) MUST be created first by the function 'clock_id()'.

      EXAMPLE in a C code:

        my_id = clock_id();        Creates a clock, returns the ID number of this clock, and starts the clock.

        t0 = clock_reset(my_id);   Resets and starts this clock. Returns 0.0.
        t1 = clock_time(my_id);    Returns the elapsed time from the last reset (double).

        clock_print();             Print on screen the running clock values.

        Debug mode:    CLOCK

Documentation in '..\Resource\codata.hdr'

     CODATA: Committee on Data for Science and Technology for international use.         link: http://www.codata.org/

     A few Physical Constants         - 2014 CODATA recommended values -

      _codata_k          Boltzmann Constant                              J.K-1
      _codata_h          Planck Constant                                 J.s

      _codata_epsilon0   Permittivity of Vacuum (aka Electric Constant)  F.m-1
      _codata_mu0        Permeability of Vacuum (aka Magnetic Constant)  H.m-1
      _codata_c0         Speed of Light in Vacuum                        m.s-1
      _codata_Z0         Characteristic Impedance of Vacuum              Ohm

      _codata_q          Elementary Charge                               C
      _codata_eV         Electron Volt                                   J
      _codata_me         Electron Mass                                   kg

      _codata_G          Newtonian Constant of Gravitation               m3.kg-1.s-2

      _codata_NA         Avogadro Constant                               mol-1
      _codata_F          Faraday Constant                                C.mol-1
      _codata_SB         Stefan-Boltzmann Constant                       W.m-2.K-4

     Source: The NIST Reference on Constants, Units and Uncertainty
     e.g.    http://physics.nist.gov/constants

     CODATA was established in 1966 as an interdisciplinary committee of the International Council of Science (ICSU), formerly the
     International Council of Scientific Unions. It seeks to improve the compilation, critical evaluation, storage, and retrieval
     of data of importance to science and technology. The CODATA Task Group on Fundamental Constants was established in 1969. Its
     purpose is to periodically provide the international scientific and technological communities with an internationally
     accepted set of values of the fundamental physical constants and closely related conversion factors for use worldwide.The
     first such CODATA set was dated 1973, the second 1986, the third 1998, the fourth 2002, the fifth 2006 and the sixth in 2010
     and the seventh (current) in 2014. Next release is expected in 2018.

     For Mathematical Constants:  see file "./mathconst.hdr".

Documentation in '..\Resource\coherent_freq.hdr'

     COHERENT SAMPLING

     Function:  'coherent_freq(..)'

     USAGE:    freq = coherent_freq(target_frequency, num_of_points, sampling_frequency)
               check_coherent_sampling(target_frequency, num_of_points, sampling_frequency, a_string)

     Coherent sampling is an important concept in signal processing. It allows to obtain better results from FFT based tools by
     removing the windowing functions and their side effects. User proposes a frequency target, function returns the closest
     coherent signal frequency. It is important to note that the coherent frequency does depend on the local sampling frequency
     and to the number of sampled data.

     Coherent sampling is the sampling of a periodic signal, where an integer number of its cycles fits into a predefined sampling
     window:

          fsig / fsampling == NWINDOW / NRECORD

          fsig:       Periodic input signal
          fsampling:  Sampling/clock frequency of the signal under test
          NWINDOW:    Integer number of cycles of signal within the sampling window
          NRECORD:    Number of data points in the sampling window

          (best to have NWINDOW a prime number to avoid repetition)

     The directive 'debug COHERENT' triggers the output of a debug information table.

Documentation in '..\Resource\collinear.hdr'

     collinear(xa,ya, xb,yb, xc,yc) returns a measure of collinearity for 3 points.

     USAGE:  tst = collinear(xa,ya, xb,yb, xc,yc)

     In order to deal with collinear points whose coordinates are not numerically exact, we compare the area of the largest square
     that can be created by the line segment between two of the points to twice the area of the triangle formed by the points.
     If the points are collinear, their triangle has zero area. If the points are close to collinear, then the area of this
     triangle will be small relative to the square of the longest segment.

Documentation in '..\Resource\complex.hdr'

     Functions on COMPLEX numbers:

          COMPLEX_TYPE*  complex_factor(r, C)             r * C
          COMPLEX_TYPE*  complex_conj(C)                  Conj(C)
          COMPLEX_TYPE*  complex_inv(C)                   1/C
          COMPLEX_TYPE*  complex_prod(C1,C2)              C1*C2
          COMPLEX_TYPE*  complex_divide(C1,C2)            C1/C2
          COMPLEX_TYPE*  complex_sum(C1,C2)               C1+C2
          COMPLEX_TYPE*  complex_substract(C1,C2)         C1-C2
          COMPLEX_TYPE*  complex_pow(C,n)                 C^n

Documentation in '..\Resource\coop.hdr'

     coop_manager()

     Function creating and managing the cooperation between the instantiations of 2 user or 2 tool functions.

     USAGE:   coop_id = coop_manager(<tag1>, <tag2>, <id>, <target>, <command>, <error_msg>);

              where   <command> is ALLOCATE or QUERY.

                      when <command> is ALLOCATE, <target> has no signification
                      when <command> is QUERY,
                           <target>  0  to query for the id of a function
                                     1  to query for the unique ID allocate to the function

              This function creates a common and unique ID number to requests with same string tags <tag1>, <tag2>.

              It is currently not possible to associate more than 2 functions together. But a set of couples may be defined.

              ALLOCATE:  allocates and returns the internal allocated ID, i.e. the index of the record.
              QUERY:     returns the id of the associate, the id given by the NAPA compiler, or -1 if there is no associate.

     Example:

       Using the function coop() in ALLOCATE mode, it is possible to associate functions:

                                            V   .
                                            V   .
                                            V   .
       ...
       n1 = coop_manager("myfun","fil.dat", 3 , 0 ,ALLOCATE,msg);  => creates and returns a unique ID:          n1 = 0
       n2 = coop_manager("myfun","foo.dat", 5 , 0 ,ALLOCATE,msg);  => creates and returns a unique ID:          n2 = 1
       n3 = coop_manager("myfun","fil.dat", 8 , 0 ,ALLOCATE,msg);  => returns ID alreays allocated to partner:  n3 = 0
       ...

       ( a table is built for functions "myfun" with tag "fil.dat" containing
         the id  3 and 8 making possible to set-up cooperation between these 2 calls )

       Using the function coop() in QUERY mode, it is now possible for one of the associates to know the unique ID or the id of
       his "partner", if any:
                                            V   V
                                            V   V
                                            V   V
       ...
       id = coop_manager("myfun","fil.dat", 3 , 0 ,QUERY,msg);  => returns the id of partner: 8 (for "myfun", partner of 3 is 8  )
       id = coop_manager("myfun","fil.dat", 8 , 0 ,QUERY,msg);  => returns the id of partner: 3 (for "myfun", partner of 8 is 3  )
       ...
       id = coop_manager("funny","fil.dat", 3 , 0 ,QUERY,msg);  => no associate, returns:    -1 (for "funny", there is no partner)
       id = coop_manager("myfun","fil.dat", 5 , 0 ,QUERY,msg);  => no associate, returns:    -1 (for "myfun", 5 has no partner   )
       ...
       ...
       id = coop_manager("myfun","fil.dat", 3 , 1 ,QUERY,msg);  => returns the unique ID:     0 (corresponding to pair of id 3&8 )
       id = coop_manager("myfun","fil.dat", 8 , 1 ,QUERY,msg);  => returns the unique ID:     0 (corresponding to pair of id 3&8 )
       id = coop_manager("myfun","foo.dat", 5 , 1 ,QUERY,msg);  => returns the unique ID:     1 (corresponding to id 5           )
       ...
       id = coop_manager("funny","fil.dat", 3 , 1 ,QUERY,msg);  => never allocated, returns: -1
       ...

       TIPS:  The QUERY value of the allocation is a unique ID value owned by the pair of associates. This value may be used to
              address a shared array.

      See "../User/wave2.hdr" for a practical example of the use of this function.

Documentation in '..\Resource\cordic.hdr'

     Floating point CORDIC algorithm      [ 'COordinate Rotation DIgital Computer' ]

     Trigonometric Functions 'CORDIC_sin(x)', 'CORDIC_cos(x)', 'CORDIC_tan(x)'

            Valid for x in interval [-Pi/2, Pi/2],
            with a number of iterations of 60, absolute error is smaller than 4.0e-16.

     TIPS:  To have an exact modeling, the number of iterations and the precision of constants must be adapted to match the
            silicon implementation.

            By default, the iteration is set to 60 and precision to 16 significant digits matching 'double float' precision.
            Run function CORDIC_tables_compute(iter, prec) to select smaller values.

     Example 1

            node    a  dalgebra  CORDIC_sin(_2pi_*freq*TIME)        //  use default set-up
            ...

     Example 2

            init void  CORDIC_tables_compute(50, 10)                //  modify set-up
            ...
            node    a  dalgebra  CORDIC_sin(_2pi_*freq*TIME)        //  and use new set-up
            ...

Documentation in '..\Resource\cpk.hdr'

     Process Capability Indices

        CP(), CPL(), CPU() and CPK()  estimate process capability
        CPM() and CPKM()              estimate process capability around a target
        CC()

Documentation in '..\Resource\crc.hdr'

        CRC-32-IEEE 802.3:   crc_of_file, crc_of_array
                             crc_engine, crc_initialize

        Code adapted from http://pmt.sourceforge.net/specs/png-1.2-pdg.html#CRCAppendix

        A cyclic redundancy check (CRC) is a type of function that takes an input of data stream of any length and produces as
        output a value of a certain fixed size. The term CRC is often used to denote either the function or the function's output.
        A CRC can be used as a checksum to detect alteration of data during transmission or storage. CRCs are popular because they
        are simple to implement in binary hardware, are easy to analyze mathematically, and are particularly good at detecting
        common errors caused by noise in transmission channels.
        The CRC was invented by W. Wesley Peterson, and published in his 1961 paper.
                                                                                                                  (from wikipedia)

Documentation in '..\Resource\crc_word.hdr'

     USAGE: crc4(n4)
            crc8(n8)
            crc16(n16)

     returns 1 if number of 1 is odd

Documentation in '..\Resource\crossing.hdr'

     Function 'y = crossing(&x, NULL, x1,x2, y1,y2)'  gives the y value of the crossing point
     Function 'x = crossing(NULL, &y, x1,x2, y1,y2)'  gives the x value of the crossing point

                 y axis                                                        y axis
                  ^                          /                                  ^                          /
                  |                         /                                   |                         /
               y2 +........................o                                 y2 +........................o
                  |                       /:                                    |                       /:
                  |                      / :                                    |                      / :
                  |                     /  :                                    |                     /  :
                ? +................... O   :                                  Y +................... O   :
                  |                   /:   :                                    |                   /:   :
                  |                  / :   :                                    |                  / :   :
                  |                 /  :   :                                    |                 /  :   :
                  |                /   :   :                                    |                /   :   :
                  |               /    :   :                                    |               /    :   :
               y1 +..............o     :   :                                 y1 +..............o     :   :
                  |             /:     :   :                                    |             /:     :   :
                  |            / :     :   :                                    |            / :     :   :
                  |           /  :     :   :                                    |           /  :     :   :
             -----+----------/---+-----+---+-------> x axis                -----+----------/---+-----+---+-------> x axis
                  |         /    x1    X   x2                                   |         /    x1    ?   x2

Documentation in '..\Resource\day.hdr'

     USAGE:   day_of_the_week(<year>, <month>, <day>)          [long]

              returns a number corresponding to the day of the week,
              0 Sunday, .. 6 Saturday

     where    <year>    1901..2099                             [long]
              <month>   JANUARY..DECEMBER   or  1..12          [long]
              <days>    1..31                                  [long]

Documentation in '..\Resource\DE1_solver.hdr'

     FIRST ORDER Differential Equation Solver [fixed step]

       USAGE: ynew = DE1_solver(dt, y_old, method, (double (*)(double)) Some_Function)

       Parameters      dt             step size
                       y_old          last value
                       method         algorithm to use (see below)
                       SomeFunction   evaluate the derivative of the field

       Algorithms currently implemented (method):
             DE1_EULER
             DE1_MODIFIED_EULER
             DE1_HEUNS
             DE1_MIDPOINT
             DE1_RUNGE_KUTTA_4
             DE1_ENGLAND_4

      EXAMPLE:   that illustrates how the above might be called

         ...
           double t;
           double dt = 0.1;                                      Step size
           double y  = 1.0;                                      Initial value
           for (t = 0; t < 100.0; t += dt) 
             (void) fprintf(stdout, "%g %g\n", t, y);
             y = DE1_solver(dt, y, DE1_MIDPOINT, (double (*)(double)) SomeFunction);
           
         ...

         The derivative function above has a simple solution.
         Find the solution to   dx(t)/dt = - 0.05*x

         double SomeFunction(double x)                          Simple derivative function
           double k = 0.05;
           return -k*x;

         The solver will compute the solution     [ which is here x(t) = exp(-k*t) ]

Documentation in '..\Resource\debug.hdr'

     Function 'tool_debug_information' to be used in the code of a NAPA tool.

     This function provides tool synchronization information at run time if desired.
     It is used inside some user-defined tools for debug purpose (tool accumulating data and processing them as a batch).

     The debug information is triggered by default.

     Directive QUIET   could be used to suppress tool debug information.
     Directive VERBOSE could be used to have more debug information.
     Directive MELODY  could be used to produce a tone at the end of each task.

     'debug TOOL' is producing the same effect as 'directive VERBOSE'

     USAGE:   tool_debug_information(mode, packet, subpacket, tag, id)

Documentation in '..\Resource\debug2.hdr'

     Function 'tool_debug2_information' to be used in the code of the NAPA tool.

     This function provides tool synchronization information at run time if desired.
     It is used inside tools "tf2_i" and "tf2_o" for debug purpose.

     The debug information is triggered by default.

     Directive QUIET   could be used to suppress tool debug information.
     Directive VERBOSE could be used to have more debug information.
     Directive MELODY  could be used to produce a tone at the end of each task.

     'debug TOOL' is producing the same effect as 'directive VERBOSE'

Documentation in '..\Resource\decimal_degree.hdr'

     USAGE:   decimal_degree(degree, minute, second)

      Convert degree coded in (degrees, minutes, seconds) in decimal degrees coded as a double float

Documentation in '..\Resource\decimal_time.hdr'

     USAGE:   decimal_day   (day, hour, minute, second)
              decimal_hour  (day, hour, minute, second)
              decimal_minute(day, hour, minute, second)
              decimal_second(day, hour, minute, second)

      Convert time coded in (days, hours, minutes, seconds) in decimal days.. seconds.
      Each input may be coded as decimal too and does not need to be bounded in the usual range of values.

      To get debugging information:    debug DEBUG_DECIMAL_TIME

Documentation in '..\Resource\dew_point.hdr'

     Dew point  ('point de rosée').

       USAGE:     dew_point(Ta, Rh)     where   <Ta> is the ambient temperature                       (°C)
                                                <Rh> is the relative humidity of the ambiant air.     ( %)

                  dew_point in [0..50] interval

       reference:          https://swat.tamu.edu/media/83147/manual_dew.pdf

Documentation in '..\Resource\dm.hdr'

       This subheader allocates DYNAMIC MEMORY used by tools or user defined functions. It brings a significant help to the
       programmer of the headers and simplifies the code.

       From http://thebesthacker.com/question/does-os-reclaim-memory-on-application-exit-in-c-duplicate.html:

         " When an application terminates, all memory will be reclaimed by the OS. The reason people preach memory
           management techniques is because so long as the app is running, any memory it's asked for will remain in
           its possession, even if it's no longer being used. Unless, of course, you were nice enough to call free. "

       To allow the simulator to track memory allocation, we STRONGLY recommend to use this resource manager for every memory
       allocation. Tracking will help to pinpoint programming errors.

       There is a built-in MEMORY GUARDBAND to check memory underflow or overflow each time a query is made or a memory is
       deallocated. It helps to avoid a crash in case of minor under/overflow but it is certainly not an excuse to leave such bugs

          DA_MANAGER(..)        array of 'R_TYPE'         <- NAPA ANALOG  SIGNAL          (double float)
          LA_MANAGER(..)        array of 'I_TYPE'         <- NAPA DIGITAL SIGNAL          (long long int)
          CA_MANAGER(..)        array of 'C_TYPE'         <- NAPA CHAR                    (char)
          FA_MANAGER(..)        array of 'L_PREC'         <- NAPA LOW  PRECISION FLOAT    (float)
          HA_MANAGER(..)        array of 'H_PREC'         <- NAPA HIGH PRECISION FLOAT    (long double float)
          IA_MANAGER(..)        array of 'long int'
          SA_MANAGER(..)        array of 'short int'
          PA_MANAGER(..)        array of address pointers <- 8 bytes (64 bits OS)

       A more generic manager is also available, with a sligthly different syntax:

          GA_MANAGER(..)        array of elements (e.g. array of structures)

       All these functions return the number of -elements- of the array.

       USAGE: to allocate/free/query/reset an array of R_TYPE    (double float):
                  DA_MANAGER(ALLOCATE, &array, number, tag)
                  DA_MANAGER(FREE,     &array, number, tag)
                  DA_MANAGER(QUERY,    &array, number, tag)
                  DA_MANAGER(RESET,    &array, number, tag)

       USAGE: to allocate/free/query/reset an array of I_TYPE    (long long int):
                  LA_MANAGER(ALLOCATE, &array, number, tag)
                  LA_MANAGER(FREE,     &array, number, tag)
                  LA_MANAGER(QUERY,    &array, number, tag)
                  LA_MANAGER(RESET,    &array, number, tag)

       USAGE: to allocate/free/query/reset an array of C_TYPE    (char):
                  CA_MANAGER(ALLOCATE, &array, number, tag)
                  CA_MANAGER(FREE,     &array, number, tag)
                  CA_MANAGER(QUERY,    &array, number, tag)
                  CA_MANAGER(RESET,    &array, number, tag)

       USAGE: to allocate/free/query/reset an array of 'L_PREC'  (float):
                  FA_MANAGER(ALLOCATE, &array, number, tag)
                  FA_MANAGER(FREE,     &array, number, tag)
                  FA_MANAGER(QUERY,    &array, number, tag)
                  FA_MANAGER(RESET,    &array, number, tag)

       USAGE: to allocate/free/query/reset an array of 'H_PREC'  (long double):
                  HA_MANAGER(ALLOCATE, &array, number, tag)
                  HA_MANAGER(FREE,     &array, number, tag)
                  HA_MANAGER(QUERY,    &array, number, tag)
                  HA_MANAGER(RESET,    &array, number, tag)

       USAGE: to allocate/free/query/reset an array of 'int':
                  IA_MANAGER(ALLOCATE, &array, number, tag)
                  IA_MANAGER(FREE,     &array, number, tag)
                  IA_MANAGER(QUERY,    &array, number, tag)
                  IA_MANAGER(RESET,    &array, number, tag)

       USAGE: to allocate/free/query/reset an array of 'short int':
                  SA_MANAGER(ALLOCATE, &array, number, tag)
                  SA_MANAGER(FREE,     &array, number, tag)
                  SA_MANAGER(QUERY,    &array, number, tag)
                  SA_MANAGER(RESET,    &array, number, tag)

       USAGE: to allocate/free/query/reset an array of pointers:
                  PA_MANAGER(ALLOCATE, &array, number, tag)
                  PA_MANAGER(FREE,     &array, number, tag)
                  PA_MANAGER(QUERY,    &array, number, tag)
                  PA_MANAGER(RESET,    &array, number, tag)

       USAGE: to allocate/free/query/reset an array of elements (e.g. structures):
                  GA_MANAGER(ALLOCATE, &array, number, size, tag)
                  GA_MANAGER(FREE,     &array, number, size, tag)
                  GA_MANAGER(QUERY,    &array, number, size, tag)
                  *** no function RESET for structures *********

       Memory is allocated and address is defined (ALLOCATE), or memory is freed and address is NULLed (FREE). 'size' is the size
       of an element of the structure. 'tag' is a string identifying the tool being used, it will be used in error or warning
       messages.

       Please note that for the allocation of array structures, i.e. GA_MANAGER() functions, it is not the number of elements but
       the size of the memory which should be indicated.

       Memory sharing: It is possible to allocate the same memory with the same size more than once (ALLOCATE). The number of
       deallocation requests (FREE) must match exactly the number of allocation requests.

       CAUTION: Allocated memory is NOT initialized. Use (RESET) after allocation.

       Number of elements currently allocated can be obtained at any time (QUERY). For this request, the number of elements in
       function call is then ignored.

       Allocation and deallocation should absolutely match (number and type of data), otherwise the simulation is stopped.

       Instruction 'debug DM' triggers the output of debug information about allocation. More extensive debug information is
       obtained by 'debug DM_DETAIL' (long!).

       Directive 'DM_LOGFILE "file.out"' output a log file containing the history of the size of the dynamic memory allocation and
       deallocation during the simulation.

       Directive 'DM_MEMORY_GUARDBAND' defines the size of a guardband below and above allocated memory. Memory leak is detected
       during the deallocation of the memory (FREE), during a request for information (QUERY) or a memory reset (RESET).
       Currently, default is set to 64 bytes. This simple mechanism does not pretend to detect any kind of memory leakages!!!

Documentation in '..\Resource\dm2.hdr'

       This subheader allocates 2D DYNAMIC MEMORY used by tools or user defined functions. It brings a significant help to the
       programmer of the headers and simplifies the code. It is worth to note that allocated memory is contiguous.

         DA2_MANAGER(..)    2D array of 'R_TYPE'         <- NAPA  ANALOG SIGNAL         (double float)
         LA2_MANAGER(..)    2D array of 'I_TYPE'         <- NAPA DIGITAL SIGNAL         (long long int)
         CA2_MANAGER(..)    2D array of 'C_TYPE'         <- NAPA CHAR                   (char)
         FA2_MANAGER(..)    2D array of 'L_PREC'         <- NAPA LOW  PRECISION FLOAT   (float)
         HA2_MANAGER(..)    2D array of 'H_PREC'         <- NAPA HIGH PRECISION FLOAT   (long double float)
         IA2_MANAGER(..)    2D array of 'long'
         SA2_MANAGER(..)    2D array of 'short int'
         PA2_MANAGER(..)    2D array of address pointers <- 8 bytes (64 bits OS)

       A more generic manager is also available, with a sligthly different syntax:

         GA2_MANAGER(..)    2D array of elements (e.g. array of structures)

       To allow the simulator to track memory allocation, it is STRONGLY recommended to
       use this resource manager for every 2D array memory allocation.

       USAGE: to allocate/free/query/reset a 2D array of R_TYPE (double float):
                  DA2_MANAGER(ALLOCATE, &array, nrow, ncol, tag)
                  DA2_MANAGER(FREE,     &array, nrow, ncol, tag)
                  DA2_MANAGER(QUERY,    &array, nrow, ncol, tag)
                  DA2_MANAGER(RESET,    &array, nrow, ncol, tag)

       USAGE: to allocate/free/query/reset a 2D array of I_TYPE (long long int):
                  LA2_MANAGER(ALLOCATE, &array, nrow, ncol, tag)
                  LA2_MANAGER(FREE,     &array, nrow, ncol, tag)
                  LA2_MANAGER(QUERY,    &array, nrow, ncol, tag)
                  LA2_MANAGER(RESET,    &array, nrow, ncol, tag)

       USAGE: to allocate/free/query/reset a 2D array of C_TYPE (char):
                  CA2_MANAGER(ALLOCATE, &array, nrow, ncol, tag)
                  CA2_MANAGER(FREE,     &array, nrow, ncol, tag)
                  CA2_MANAGER(QUERY,    &array, nrow, ncol, tag)
                  CA2_MANAGER(RESET,    &array, nrow, ncol, tag)

       USAGE: to allocate/free/query/reset a 2D array of 'float':
                  FA2_MANAGER(ALLOCATE, &array, nrow, ncol, tag)
                  FA2_MANAGER(FREE,     &array, nrow, ncol, tag)
                  FA2_MANAGER(QUERY,    &array, nrow, ncol, tag)
                  FA2_MANAGER(RESET,    &array, nrow, ncol, tag)

       USAGE: to allocate/free/query/reset a 2D array of 'H_PREC':
                  HA2_MANAGER(ALLOCATE, &array, nrow, ncol, tag)
                  HA2_MANAGER(FREE,     &array, nrow, ncol, tag)
                  HA2_MANAGER(QUERY,    &array, nrow, ncol, tag)
                  HA2_MANAGER(RESET,    &array, nrow, ncol, tag)

       USAGE: to allocate/free/query/reset a 2D array of 'int':
                  IA2_MANAGER(ALLOCATE, &array, nrow, ncol, tag)
                  IA2_MANAGER(FREE,     &array, nrow, ncol, tag)
                  IA2_MANAGER(QUERY,    &array, nrow, ncol, tag)
                  IA2_MANAGER(RESET,    &array, nrow, ncol, tag)

       USAGE: to allocate/free/query/reset a 2D array of 'short int'
                  SA2_MANAGER(ALLOCATE, &array, nrow, ncol, tag)
                  SA2_MANAGER(FREE,     &array, nrow, ncol, tag)
                  SA2_MANAGER(QUERY,    &array, nrow, ncol, tag)
                  SA2_MANAGER(RESET,    &array, nrow, ncol, tag)

       USAGE: to allocate/free/query/reset a 2D array of pointers:
                  PA2_MANAGER(ALLOCATE, &array, nrow, ncol, tag)
                  PA2_MANAGER(FREE,     &array, nrow, ncol, tag)
                  PA2_MANAGER(QUERY,    &array, nrow, ncol, tag)
                  PA2_MANAGER(RESET,    &array, nrow, ncol, tag)

       USAGE: to allocate/free/query/reset a 2D array of elements (e.g. structures):
                  GA2_MANAGER(ALLOCATE, &array, nrow, ncol, size, tag)
                  GA2_MANAGER(FREE,     &array, nrow, ncol, size, tag)
                  GA2_MANAGER(QUERY,    &array, nrow, ncol, size, tag)
                  *** no function RESET for structures **************

       Memory is allocated and address is defined (ALLOCATE), or memory is freed and address is NULLed (FREE). 'nrow', 'ncol' are
       resp the number of rows or columns to allocated. 'size' is the size of an element of the structure. 'tag' is a string
       identifying the tool being used, it will be used in error or warning messages.

       Caution: Allocated memory is NOT initialized. Use (RESET) after allocation.

       Number of elements currently allocated can be obtained at any time (QUERY).
       With ('nrol', 'ncol') resp. equal to (true, false) or (false, true) the output is resp. the number of rows or the number
       of columns of the allocated 2D array. For other values, the output is the total number of elements of the 2D array.

       Allocation and deallocation should absolutely match (number and type of data), otherwise the simulation is stopped.

       Directive 'debug DM2' triggers the output of debug information about 2D allocation.
       As this function uses the dynamic memory manager from file "./dm.hdr", please refer to this file for other directives.
       Use Directive 'DM_LOGFILE "file.out"' as described in file "dm.hdr" to output a log file containing the history of the size
       of the dynamic memory allocation and deallocation during the simulation.

Documentation in '..\Resource\endian.hdr'

     Function:  'test_endianness()'

Documentation in '..\Resource\eng.hdr'

     Function 'eng(<x>, <n>)'
        formats formatted_number <x> in engineering format with <n> significant digits
        if <n> <= 3, uses a fixed format

     Using the standardized prefixes:          "http://www.physics.nist.gov/cuu/Units/prefixes.html"

        'y'    yocto   10^-24
        'z'    zepto   10^-21
        'a'     atto   10^-18
        'f'    femto   10^-15
        'p'     pico   10^-12
        'n'     nano   10^-09
        'u'    micro   10^-06                  unhappily the greek character for 'micro' is not portable, replaced here by 'u'
        'm'    milli   10^-03

        'k'     kilo   10^+03
        'M'     mega   10^+06
        'G'     giga   10^+09
        'T'     tera   10^+12
        'P'     peta   10^+15
        'E'      exa   10^+18
        'Z'    zetta   10^+21
        'Y'    yotta   10^+24

Documentation in '..\Resource\error_function.hdr'

     Functions 'error_function()', 'complementary_error_function()', 'inverse_error_function()'

Documentation in '..\Resource\factor.hdr'

     Function   'f = extract_a_factor(&n)'   returns f, a factor of n, and the number n divided by this value
     Function   'print_factors(n)'
     Function   'b = isprime(n)'             returns true if the number n is a prime number

Documentation in '..\Resource\farey.hdr'

      Farey sequence: num = fareysequence(N,  true)        prints fractions of  ascending Farey sequence from  0/1  to  1/0
                      num = fareysequence(N, false)        prints fractions of descending Farey sequence from  1/0  to  0/1
      this function returns the number of terms

      In mathematics, the Farey sequence of order n is the sequence of completely reduced fractions,
      either between 0 and 1, or without this restriction, which when in lowest terms have denominators
      less than or equal to n, arranged in order of increasing size. With the restricted definition,
      each Farey sequence starts with the value 0, denoted by the fraction 0/1, and ends with the value 1,
      denoted by the fraction 1/1.

      Examples: the Farey sequences of orders 1 to 8 are :

      F1 =   0/1,                                                                                                          1/1
      F2 =   0/1,                                                   1/2,                                                   1/1
      F3 =   0/1,                               1/3,                1/2,                2/3,                               1/1
      F4 =   0/1,                     1/4,      1/3,                1/2,                2/3,      3/4,                     1/1
      F5 =   0/1,                1/5, 1/4,      1/3,      2/5,      1/2,      3/5,      2/3,      3/4, 4/5,                1/1
      F6 =   0/1,           1/6, 1/5, 1/4,      1/3,      2/5,      1/2,      3/5,      2/3,      3/4, 4/5, 5/6,           1/1
      F7 =   0/1,      1/7, 1/6, 1/5, 1/4, 2/7, 1/3,      2/5, 3/7, 1/2, 4/7, 3/5,      2/3, 5/7, 3/4, 4/5, 5/6, 6/7,      1/1
      F8 =   0/1, 1/8, 1/7, 1/6, 1/5, 1/4, 2/7, 1/3, 3/8, 2/5, 3/7, 1/2, 4/7, 3/5, 5/8, 2/3, 5/7, 3/4, 4/5, 5/6, 6/7, 7/8, 1/1

Documentation in '..\Resource\fast_trigonometric.hdr'

     void fast_sin_table(*table, n, num)  creates the first n elements of a   sinewave where a full period contains num points,
     void fast_cos_table(*table, n, num)  creates the first n elements of a cosinewave where a full period contains num points

       Where table[] should be allocated as an array of double containing at least n points.

       The resonator is implemented as a 2-pole filter described by the following difference equation:

            X[n] = k * X[n-1] - X[n-2]       whith k = 2.0 * cos(2Pi * freq/FSL)     (constant)

            To start the oscillator, set

            X[n-1] = sin(phase)
            X[n-2] = sin(phase - (2Pi*freq/FSL))
                                  ______    ____
                                 |      |  |    |
            +--------------------| * -1  >-|    |
            |                    |______|  |    |
            |                     ______   |sum  >--+
            |                    |      |  |    |   |
            |                +---| * k   >-|    |   |
            |                |   |______|  |____|   |
            |    ______      |    ______            |
            |   |      |     |   |      |           |
            +--< delay |--+--+--< delay |-----------+
                |______|  |      |______|
                          |
                          +---------------------------> out

Documentation in '..\Resource\FFT.hdr'

      FFT of an array of COMPLEX numbers rsig_t, isig_t. Output in arrays rsig_f, isig_f.
      For processing FFT of REAL numbers, use NULL pointer for imaginary parts of data.

       >>>> Results must be divided by 'np' to obtain coefficients of the Fourier series!

      FFT:
      - the number 'np' of samples can be any positive integer.

      BUT   - power of 2 is recommended
            - other numbers will be handled at lower speed, but multiple of large prime numbers will slow down the FFT!

      Uses precomputed sine and cosine tables s and c.
      All necessary storage must be allocated before function call.

      USAGE:

      Table of data (real part):    rsig_t[0..np-1]             (after window weighting)
      Table of data (imag part):    isig_t[0..np-1]             (after window weighting)

      Allocate array of double:     rsig_f[0..np-1]             (see DA_MANAGER)
      Allocate array of double:     isig_f[0..np-1]             (see DA_MANAGER)

      Precompute table of sine  :  sintab[0..np-1]              (see SC_MANAGER)
      Precompute table of cosine:  costab[0..np-1]              (see SC_MANAGER)

      Function call for a COMPLEX SIGNAL
      FFT(rsig_t, isig_t, sintab, costab, rsig_f, isig_f, np);

      Function call for a REAL SIGNAL
      FFT(rsig_t,   NULL, sintab, costab, rsig_f, isig_f, np);

Documentation in '..\Resource\fft16.hdr'

     FFT16(input[16],output[16]);    FFT of a real 16 points regularly sampled real value signal.

     INPUT  [0..15]:

     i[ 0]   i[ 1]   i[ 2]   i[ 3]   i[ 4]   i[ 5]   i[ 6]   i[ 7]   i[ 8]   i[ 9]   i[10]   i[11]   i[12]   i[13]   i[14]   i[15]

     OUTPUT [0..15]:

     (o[ 0], 0.0 ) (o[ 1],  o[ 9]) (o[ 2],  o[10]) (o[ 3],  o[11]) (o[ 4],  o[12]) (o[ 5],  o[13]) (o[ 6],  o[14]) (o[ 7],  o[15])
     (o[ 8], 0.0 ) (o[ 7], -o[15]) (o[ 6], -o[14]) (o[ 5], -o[13]) (o[ 4], -o[12]) (o[ 3], -o[11]) (o[ 2], -o[ 9]) (o[ 1], -o[ 8])

     This C code computes the 16 point real FFT using the split radix algorithm. This code requires 79 adds and 10 multiplies.

Documentation in '..\Resource\fgetline.hdr'

     User function 'fgetline(str, fp, keep_new_line)

Documentation in '..\Resource\fibonacci.hdr'

      USAGE:           y = fibonacci(n,x)         Fibonacci polynomial
                       k = FIBONACCI(n)           Fibonacci number

     In mathematics, Fibonacci polynomials are a generalization of FIBONACCI NUMBERS.
     These polynomials are defined by:

     F[0,x] =  0
     F[1,x] =  1
     F[n,x] =  x F[n-1,x] + F[n-2,x]    if  n >= 2

     The Fibonacci numbers are recovered by evaluating the polynomials at x = 1.

     The first few FIBONACCI POLYNOMIALS / numbers are:

     F[0,x] = 0                         ->    Fn[0] = 0
     F[1,x] = 1                         ->    Fn[1] = 1
     F[2,x] = x                         ->    Fn[2] = 1
     F[3,x] = 1 + x^2                   ->    Fn[3] = 2
     F[4,x] = 2 x + x^3                 ->    Fn[4] = 3
     F[5,x] = 1 + 3 x^2 + x^4           ->    Fn[5] = 5
     F[6,x] = 3 x + 4 x^3 +  x^5        ->    Fn[6] = 8
     ...                                 ...

Documentation in '..\Resource\file.hdr'

     Function 'is_file_exist("fnam")'  checks the existence of file 'fnam'
     Function 'file_size("fnam")'      returns the size of file <fnam> in bytes, the file cannot be in use when it is called.

Documentation in '..\Resource\format.hdr'

      Function 'remove_prefix(nam)'      remove NAPA prefix 'node_' or 'var_' from NAPA identifier 'nam'
      Function 'get_prefix(nam)'         get NAPA prefix 'node_' or 'var_' from NAPA identifier 'nam'
      Function 'split_name(nam, ext)'    split the name 'nam' and the extension 'ext' of a file name 'nam'

Documentation in '..\Resource\fprintf.hdr'

     Functions 'f1printf(fptr, ...)',         'f1flush(fptr)'
      equivalent resp. to 'fprintf()', fflush() but accepting a NULL pointer

     Functions 'f2printf(fptr1, fptr2, ...)', 'f2flush(fptr1, fptr2)'
      double output equivalent resp. to  'fprintf()', fflush() and accepting NULL pointers

Documentation in '..\Resource\frac_approx.hdr'

      Function  frac_approx(val, &n, &d, errormax) approximates 'val' by a fraction 'n/d'
      Returns the residue. New values for n and d replace the former ones.

      Use  'debug  FRAC_APPROX'   to get informations on the iterations.

      Example in a C code file:

         long   n;
         long   d;
         double r;
         r = frac_approx(_pi_, &n, &d, 1.0e-9);
         (void) fprintf(stderr, " Pi is approximatively equal to %ld/%ld   (error %e)\n", n, d, r);

Documentation in '..\Resource\freq.hdr'

     Determines the frequency of the fundamental of a periodic signal.
     Valid for signals having a strong first harmonic (sinewave, triangle...).
     Request a periodic sampling.

     USAGE
               freq_out = determine_fundamental(*<data>, <freq_in>, <numofpoints>, <"tag">)

               <data>         is an array containing the signal to evaluate
               <freq_in>      0.0, if larger than 0.0, this is the frequency of the signal and there is no evaluation!
               <numofpoints>  is the number of points to analyze
               <"tag">        is given by the user to document eror or warning message

     CONVERGENCE IS NOT GRANTED! If there is no convergence, the simulation is stopped.

     Instruction 'debug FREQ' triggers the output about computation iterations.

Documentation in '..\Resource\FSM.hdr'

     Macros FSM, FSM_STATE(s), FSM_NEXT_STATE(s) to create Finite State Machines

     USAGE, EXAMPLE:

       FSM 
         FSM_STATE(s1):
             ... do stuff ...
             FSM_NEXT_STATE(s2);

         FSM_STATE(s2):
             ... do stuff ...
             if (0 > k)  FSM_NEXT_STATE(s); 
                      --> fallthrough as the switch() cases

         FSM_STATE(s3):
             ... final stuff ...
         break;    --> Exit from the FSM

     The states s1, s2... are alphanumeric ID and CANNOT be defined as constant or variable.

Documentation in '..\Resource\gabor.hdr'

     Gaussian Weighted Sinusoid

     USAGE:   gabor(<x>, <m>, <s>, <T>)

              the center of the function is at <x> = <m>,
              the width is given by the standard deviation <s> of the Gaussian,
              the number of cycles within the envelop is <T>.

Documentation in '..\Resource\gamma.hdr'

     Functions 'gamma()', 'log_gamma()'

Documentation in '..\Resource\ganging.hdr'

     Function 'rearrange_ganging_parameters()'  used to order parameters in 'ganging by name' in duser 'sarc' function

Documentation in '..\Resource\gaussian.hdr'

     the function  'gaussian(<x>, <a>, <b>, <c>)'
     where <a> is the amplitude
           <b> is the offset
           <c> is the scaling

Documentation in '..\Resource\gaussmat.hdr'

     Gauss matrix utilities for curve fitting algorithms.

      directive 'debug GAUSS_MATRIX' triggers the output of a debug information table.

Documentation in '..\Resource\goertzel.hdr'

       Second Order Goertzel algorithm, aka Watt's algorithm.
       The Goertzel algorithm computes one point of a DFT.

       >>>>>  If less than n = log2(N) points are required, Goertzel is more efficient than the Fast Fourier Transform (FFT).
       Example for a real signal:    for    N =      1 000       n <= 10
                                            N =     10 000       n <= 13
                                            N =    100 000       n <= 16
                                            N =  1 000 000       n <= 20
                                            N = 10 000 000       n <= 23

Documentation in '..\Resource\golay2.hdr'

     A few Golay Code Binary Pairs

Documentation in '..\Resource\gompertz.hdr'

     Function  'gompertz(t, a, k)'                     Assymetric Sigmoid

Documentation in '..\Resource\gray.hdr'

     Gray to Long and Long to Gray converters

     USAGE:   long_to_gray( <n> )      where input and output are unsigned long integer
              gray_to_long( <g> )

Documentation in '..\Resource\haversine.hdr'

     Haversine Solution of angle in spherical trigonometry.

     Calculate angle between two points specified by latitude/longitude using Haversine formula on a sphere.

         ********************************************************************
         *****   CAUTION!       UNDERSTAND SIGN CONVENTIONS!!!          *****
         ********************************************************************

     USAGE:   angle = haversine_angle(<lat1>, <lon1>,  <lat2>, <lon2>)         [radians]

              where <lat1>, <lon1> are geodesic location of point 1    [decimal degrees]
              where <lat2>, <lon2> are geodesic location of point 2    [decimal degrees]

     Calculate angle between two points specified by elevation/azimuth Haversine formula on a sphere.

     USAGE:   angle = haversine_angle(<elev1>, <azim1>,  <elev2>, <azim2>)     [radians]

              where <elev1>, <azim1> are coordinates of point 1        [decimal degrees]
              where <elev2>, <azim2> are coordinates of point 2        [decimal degrees]

     NOTE:    See also lawofcosine formula in "lawofcosine.hdr".

     Haversine Solution of Geodesics on a theoretical spherical earth.
     Calculate geodesic distance (in m) between two points specified by lat/long (in decimal degrees) using Haversine formula.

     USAGE:   dist  = haversine_distance(<lat1>, <lon1>,  <lat2>, <lon2>)       [meters]

              where <lat1>, <lon1> are geodesic location of point 1    [decimal degrees]
              where <lat2>, <lon2> are geodesic location of point 2    [decimal degrees]

         *** CAUTION!  Signs convention:    Northern hemisphere    latitude  [+]
                                            Southern hemisphere    latitude  [-]
                                            Eastern  hemisphere    longitude [+]     <<<< Greenwich
                                            Western  hemisphere    longitude [-]     <<<<

     NOTE:    See also LAWOFCOSINE formula. But for high precision, consider to use the VINCENTY distance based on an ellipsoid
              model of the earth in "vincenty.hdr"

     Accuracy:  since the earth is not quite a sphere, there are small errors in using spherical geometry; the earth is actually
     roughly ellipsoidal (or more precisely, oblate spheroidal) with a radius varying between about 6378 km (equatorial) and
     6357 km (polar), and local radius of curvature varying from 6336km (equatorial meridian) to 6399 km (polar).

     TIPS:  for latitude/longitude data, use tool like in    http://www.earthtools.org/

Documentation in '..\Resource\hazard.hdr'

      Hazard Function                hazard(x)               with   0.0 <= x < 1.0
      Cumulative Hazard Function     cumulative_hazard(x)    with   0.0 <= x < 1.0

Documentation in '..\Resource\help.hdr'

     Help to debug the headers. For NAPA headers developpers!

     Use 'HELP(xxx);' dropped in your header file to help the debug of complex situations.
     It will be active if the directive 'debug HELP' has been placed in the original NAPA header file

     'directive WAIT_IN_HELP NNN', where NNN is a number of seconds, inserts a wait time after each debug output. Default is 1.

Documentation in '..\Resource\humidex.hdr'

       Humidex

       USAGE:  humidex(Ta, Rh)          where   <Ta> is the ambient temperature                      (°C)
                                                <Rh> is the relative humidity of the ambiant air.    ( %)

       The current formula for determining the humidex was developed by
       J. M. Masterton and F. A. Richardson of Canada's Atmospheric Environment Service in 1979.
       Humidex differs from the heat index used in the United States in being derived from the
       dew point rather than the relative humidity. Humidex has no unit to distinguish to ambient temperature.

       reference: wikipedia    https://fr.wikipedia.org/wiki/Humidex

       Range of Humidex: Scale of comfort:

       [20 .. 29]    Feeling of well-being.
       [30 .. 39]    Some discomfort.
       [40 .. 44]    Great discomfort, avoid exertion!
       [45 .. 53]    DANGEROUS, heat stroke quite possible!
       [54 ..   ]    DANGEROUS  Heat stroke is imminent!

Documentation in '..\Resource\ifft.hdr'

      IFFT of an array of COMPLEX numbers rsig, isig. Output in arrays fr1, fi1.

       >>>> Results must be divided by 'np' to obtain coefficients of the Fourier series!

      ifft:
      - the number 'np' of samples can be any positive integer.

      BUT   - power of 2 is recommended (algorithm 4 times faster)
            - other numbers will be handled at lower speed, but multiple of large prime numbers will slow down the IFFT!

      Uses precomputed sine and cosine tables s and c. All necessary storage must be allocated before function call.

      USAGE:

      Table of data (real part):    rsig_f[0..np-1]             (after window weighting  )
      Table of data (imag part):    isig_f[0..np-1]             (after window weighting  )

      Allocate array of double:     rsig_t[0..np-1]             (see DA_MANAGER)
      Allocate array of double:     isig_t[0..np-1]             (see DA_MANAGER)

      Precomputed table of sine  :  sintab[0..np-1]             (see SC_MANAGER)
      Precomputed table of cosine:  costab[0..np-1]             (see SC_MANAGER)

      Function call for a COMPLEX SIGNAL
      IFFT(rsig_f, isig_f, sintab, costab, rsig_t, isig_t, np);

Documentation in '..\Resource\interpolation.hdr'

     Interpolation functions

      y = linear_interpolate(mu, y1, y2)
      y = cosine_interpolate(mu, y1, y2)
      y = cubic_interpolate (mu, y0, y1, y2, y3)

      y = hermite_interpolate(mu, y0, y1, y2, y3, tension, bias)
          where  tension:   1.0 is high, 0.0 is normal, -1.0 is low
                 bias:      0.0      is even,
                            positive is towards first segment,
                            negative is towards the other

      macro function INTERPOLATE_MU(x, x1, x2) computes 'mu'

      [ see also spline functions in file ../spline.hdr ]

         |                                        y3
         |                y1                      ^
         |                ^      y?               :
         |                :      ^                :
         |                :      :     y2         :                        x  - x1
         |        y0      :      :     ^          :            <----  mu = -------
         |        ^       :      :     :          :                        x2 - x1
         |        :       :      :     :          :
         |        :       :      :     :          :
         |________:_______:______:_____:__________:_____________
                  x0      x1     x     x2         x3

Documentation in '..\Resource\intersect.hdr'

     Function intersect(xa,ya, xb,yb, xc,yc) is true if line ((xa,ya),(xb,yb)) intersects line ((xc,yc),(xd,yd)).

Documentation in '..\Resource\invnorm.hdr'

     The function 'invnorm(p)' with  0.0 <= p <= 1.0
     The function 'create_invnorm_gnuplot_profile(filnam)' creates a file containing the Gnuplot profile for such a set of data.

     The function 'invnorm(p)' is used to build the Normal Probability Plot, and exists in Gnuplot.
     If this function is applied to a cumulative histogram of a perfect normal distribution, the output is a straight line.
     This is a very efficient method to evaluate the 'normality' of s set of data.

     The inverse normal cumulative distribution is a non-linear function for which no closed-form solution exists.
     The function is continuous, monotonically increasing, infinitely differentiable, and maps the open interval (0,1)
     to the whole real line.

     Gnuplot invnorm profile file is automatically generated, default is file name "_my_profile_invnorm.plt"
       to redirect profile in file <output_file_name>:      directive GNUPLOT_INVNORM_PROFILE_FILE_NAME  <output_file_name>

Documentation in '..\Resource\isnumber.hdr'

     'is_a_number(str)'             test a string as a number
     'is_an_integer_number(str)'    test a number as an integer number

Documentation in '..\Resource\jaro.hdr'

      The jaro_wrinkler function returns a double precision value from 0.0 to 1.0, i.e from total disagreement to
      character-by-character agreement. The returned value is a measure of the similarity of the two strings.

      More information can be found on <http://en.wikipedia.org/wiki/Jaro-Winkler>

      See also "./levenstein.hdr" and "./metaphone.hdr"

     USAGE:

      out = jaro_wrinkler(<ying>, <yang>, <opt0>, <opt1>);

      <ying> and <yang> are pointers to the two strings to be compared.

      The options are                  [true or false],    false indicates the option is deactivated.

          <opt0>   Increase the probability of a match when the number of matched characters is large. This option allows for a
                   little more tolerance when the strings are large. It is not an appropriate test when comparing fixed length
                   fields such as phone and social security numbers.
          <opt1>   All lower case characters are converted to upper case prior to the comparison. Disabling this feature means
                   that the lower case string "code" will not be recognized as the same as the upper case string "CODE".
                   Also, the adjustment for similar characters section only applies to uppercase characters.

          The suggested values for options are false for character strings such as names.

Documentation in '..\Resource\julianday.hdr'

     USAGE:   julian_days(<year>, <month>, <day>, <universal_time>)       [decimal days]
              returns the julian day number

     USAGE:   dy2k(<year>, <month>, <day>, <universal_time>)              [decimal days]
              returns the number of days from Year 2000

     where    <year>    NNNN                                              [long]
              <month>   JANUARY..DECEMBER   or   1..12                    [long]
              <days>    1..31                                             [long]
              <universal time>                                            [decimal hours]

     A Julian date or day number is the number of elapsed days since the beginning of a cycle of 7980 years invented by Joseph
     Scaliger in 1583. The purpose of the system is to make it easy to compute an integer (whole number) difference between one
     calendar date and another calendar date. The 7980 year cycle was derived by combining several traditional time cycles (solar,
     lunar, and a particular Roman tax cycle) for which 7980 was a common multiple. The starting point for the first Julian cycle
     began on January 1, 4713 B.C. NOON UTC (Gregorian calendar) and will end on January 22, 3268. The following day will begin
     the first day of the second Julian date period (or 7980 year cycle).

     Number of days from year 2000 is another metric. Years are restricted to 1901..2099.
     It returns the number of days where 0.0 is 1999 DECEMBER 31, MIDNIGHT UTC.

Documentation in '..\Resource\lambertw.hdr'

     LAMBERT W-Function, aka 'Omega' function or 'product log' function.

       'lambertw(x)'

                                                                                   w
        The function of Lambert-w-function is the inverse function of  f(w) = w * E

        equation:      y = x * exp(x)
        solution:      x = lambertw(y)

        Example:

        equation:      exp(-c*x) = a * (x - b)
        solution:      x = b + (1/c) * lambertw(c * exp(-b*c)/a)

Documentation in '..\Resource\lawofcosine.hdr'

     Law of Cosine Solution of angle in spherical trigonometry.

     Calculate angle between two points specified by latitude/longitude using Law of Cosine on a sphere.

         ********************************************************************
         *****   CAUTION!       UNDERSTAND SIGN CONVENTIONS!!!          *****
         ********************************************************************

     USAGE:   angle = lawofcosine_angle(<lat1>, <lon1>,  <lat2>, <lon2>)      [radians]

              where <lat1>, <lon1> are geodesic location of point 1   [decimal degrees]
              where <lat2>, <lon2> are geodesic location of point 2   [decimal degrees]

     Calculate angle between two points specified by elevation/azimuth using Law of Cosine on a sphere.

     USAGE:   angle = lawofcosine_angle(<elev1>, <azim1>,  <elev2>, <azim2>)  [radians]

              where <elev1>, <azim1> are coordinates of point 1       [decimal degrees]
              where <elev2>, <azim2> are coordinates of point 2       [decimal degrees]

     NOTE:    See also Haversine formula in "haversine.hdr".

     Law of Cosine Solution of Geodesics on a theoretical spherical earth.
     Calculate geodesic distance (in m) between 2 points specified by latitude/longitude (in decimal degrees) using Law of Cosine.

     USAGE:   dist  = lawofcosine_distance(<lat1>, <lon1>,  <lat2>, <lon2>)    [meters]

              where <lat1>, <lon1> are geodesic location of point 1   [decimal degrees]
              where <lat2>, <lon2> are geodesic location of point 2   [decimal degrees]

         *** CAUTION!  Signs convention:    Northern hemisphere     latitude  [+]
                                            Southern hemisphere     latitude  [-]
                                            Eastern  hemisphere     longitude [+]    <<<<
                                            Western  hemisphere     longitude [-]    <<<<

     NOTE:    See also Haversine formula and for high precision, consider to use the Vincenty distance based on an ellipsoid model
              of the earth ("\Simulate\NapaDos\Hdr\Resource\vincenty.hdr")

     Accuracy:  since the earth is not quite a sphere, there are small errors in using spherical geometry; the earth is actually
     roughly ellipsoidal (or more precisely, oblate spheroidal) with a radius varying between about 6378 km (equatorial) and
     6357 km (polar), and local radius of curvature varying from 6336 km (equatorial meridian) to 6399 km (polar).

     TIPS:  for latitude/longitude data, use tool like in    http://www.earthtools.org/

Documentation in '..\Resource\levenshtein.hdr'

     Function 'levenshtein(str1, str2)' computes the Levenshtein distance between strings
     function 'damerau_levenshtein(str1, str2)' computes the Damerau_Levenshtein distance.

      The Levenshtein distance between two strings is given by the minimum number of operations needed to transform one string
      into the other, where an operation is an insertion, deletion, or substitution of a single character. The Damerau_Levenshtein
      distance is an improvement of the Levenshtein distance by considering transposition.

      See also "./metaphone.hdr" and "./jaro.hdr"

Documentation in '..\Resource\line.hdr'

     User functions 'clean_eol()' ,  'strip_non_alnum()',  'strip_separator()'

     clean_eol(string) cleans the end of the line, removing spaces and right end comments (//)
     It clears also plain line of comments (line starting with #).
     Tabs, if any, are replaced by one single blank space.

     Returns   true   if line contains data,
               false  otherwise.
               The content of the line is modified

     strip_non_alnum(string) cleans the line, keeping only text and numbers
     It keeps also the non alphanumeric characters: spaces, slash, end of line.

     Returns   true   if line contains data,
               false  otherwise.
               The content of the line is modified.

     strip_separator(string, character) cleans the line from separator.

Documentation in '..\Resource\linregress.hdr'

      Linear Regression

         y(x) = a + b*x, for n samples
         The following assumes the standard deviations are unknown for the set of data x and y
         Return a, b and the regression coefficient r

         status = lin_regress(*x, *y, n, *a, *b, *r)

Documentation in '..\Resource\list.hdr'

     Minimum, Maximum and Mean of a list of data.

     Functions:    m = minimum_of_list(list,n)           Min[ list[]   ]
                   m = maximum_of_list(list,n)           Max[ list[]   ]
                   m = mean_of_list   (list,n)           Sum[ list[]   ] / n
                   m = mean2_of_list  (list,n)           Sum[ list[]**2] / n
                   m = rms_of_list    (list,n)           Sqrt[Sum[list[]**2] / n]

     Check the number of elements <n> to avoid memory leakage!!!

Documentation in '..\Resource\lsp.hdr'

     FFT of an array of REAL numbers (tim, sig). Output in array (mag).
     Lomb-Scargle Periodogram for unevenly spaced data.

     Reference: Search Algorithm for Weak Periodic Signals in Unevenly Spaced Data
                Computers in Physics, Nov/Dec 1988  pp 77-82
                William H. Press, Saul A. Teukolsky

       >>>> Results must be divided by 'np', the number of samples, to obtain coefficients of the LSP series!

      directive 'debug LSP' triggers the output of information about LSP computation.

Documentation in '..\Resource\LU.hdr'

     Functions LU_decomposition() and LU_backsubstitution()
     These routines are used in combination to solve linear equations or invert a matrix.

     Caution: indexes start at 1!!

Documentation in '..\Resource\luhn.hdr'

     Luhn algorithm

Documentation in '..\Resource\match.hdr'

     Function 'match(pattern, string) with pattern using wildcards '?' and '*', returns 0 (no match) or 1 (match).

     Wildcard '?'  replaces 1 and only 1 character
     Wildcard '*'  replaces 0 or several characters
     Wildcard '?*'  replace 1 or several characters

     Example   match("a?b*c?*.d", "ambiance.d")   returns 1.
               match("a?b*c?*.d", "ambiances.d")  returns 1.

Documentation in '..\Resource\mathconst.hdr'

     A few Mathematical Constants

        Golden_Ratio_Phi             1.61803 39887 49894 84820 458680...
        Golden_Ratio_phi             0.61803 39887 49894 84820 458680...
        Euler_Mascheroni             0.57721 56649 01532 86060 651209...

        _PI_, _PI2_, _PI4_, _PI8_, _2PI_, _E_  defined in C simulator produced by NAPA

     For Physical Constants:  see file "./codata.hdr".

Documentation in '..\Resource\metaphone.hdr'

      Phonetic string matching

      int  metaphone_strcmp(...)
      void metaphone(...)

      The Metaphone algorithm was developed by Lawrence Phillips. Like the Soundex algorithm, it compares words that sound alike
      but are spelled differently. Metaphone was designed to overcome difficulties encountered with Soundex.

      USAGE:   <out> = metaphone_strcmp(<stri1>, <stri2>)
               where <stri1> and <stri2> are the strings to be compared
                     <out> is equivalent to ANSI-C strcmp(...)

      USAGE:   metaphone(<stri>, <stro>)
               where <stri> is a string to be reduced by the function
                     <stro> is the string reduced to _METAPHONE_LENGTH uppercase letters

      _METAPHONE_LENGTH is the length of the Metaphone code. FYI, a good compromise value for English names is 4.

      For comparing words which are not names or for some non-English names, use a longer code length for more precise matches.

      To change this length:
               directive _METAPHONE_LENGTH   <an_integer_number>

      See also "./levenstein.hdr" and "./jaro.hdr"

Documentation in '..\Resource\metric.hdr'

      Exotic/Metric Conversion Macros

      ******************   length:  inch, foot, mile, yard     ( "international measure" [SIC] )

        FOOT_TO_METER()
        INCH_TO_METER()
        MILE_TO_METER()
        YARD_TO_METER()

        METER_TO_FOOT()
        METER_TO_INCH()
        METER_TO_MILE()
        METER_TO_YARD()

        FOOT_TO_INCH()
        FOOT_TO_MILE()
        FOOT_TO_YARD()
        INCH_TO_FOOT()
        INCH_TO_MILE()
        INCH_TO_YARD()
        MILE_TO_FOOT()
        MILE_TO_INCH()
        MILE_TO_YARD()
        YARD_TO_FOOT()
        YARD_TO_INCH()
        YARD_TO_MILE()

      ******************   mass:    ounce, pound               ( "avoirdupois" )

        OUNCE_TO_KG()
        KG_TO_OUNCE()

        POUND_TO_KG()
        KG_TO_POUND()

        OUNCE_TO_POUND()
        POUND_TO_OUNCE()

Documentation in '..\Resource\mix_bits.hdr'

      Function to mix the first n bits of a long long integer
      USAGE:   mix_bits(num, n)

       EDITION ON GOING!

Documentation in '..\Resource\month.hdr'

     Macros JANUARY, .. DECEMBER                coded as 1, .. 12
     Array of strings  monthsoftheyear[13][9]

Documentation in '..\Resource\narg.hdr'

     The PP_NARG(...) macro returns the number of arguments that have been passed to it.
     To be used to get the number of arguments of a variadic function up to 64 arguments.

     AN EXAMPLE:   macro function FOO()

       #include "/Simulate/NapaDos/Hdr/Resource/narg.hdr"

       #define FOO(...)   _foo(PP_NARG(__VA_ARGS__), __VA_ARGS__)
                                  |                      |
                    +-------------+                      |
                    |                                    |
                    |         +--------------------------+
                    |         |
                    V         V
       void _foo(int nparms, ...);

       void _foo(int nparms, ...) 

         return;

Documentation in '..\Resource\nCm.hdr'

     Compute nCm = C(n,m) = the number of combinations of n items, taken m at a time.
     C(n,m) aka binomial coefficient

     The definition of this function is  nCm = C(n,m)  = n! / (m! * (n-m)!).
     Computing this formula can cause overflow for large values of n, even when C(n,m) would be defined.

     It will not overflow if C(n,m) < LONG_MAX
     Function domain: n >= 0,  0 <= m <= n.

     See also binomial()

Documentation in '..\Resource\nextpower2.hdr'

     Function 'next_power_of_2(n)'
     MACRO    'NEXT_POWER_OF_2(n)'

Documentation in '..\Resource\nicetics.hdr'

      Function  nicetics()  computes a nice set of tics corresponding to data range.

      USAGE:

      nicetics(min, max, maxticks, *nicemin, *nicemax, *range, *tickspacing)

      min, max:   inputs
      maxticks:   input, max number of ticks

Documentation in '..\Resource\norm.hdr'

     Norm a set of data.

     Functions:   norm0(<data>, <n>)    ( =>  min = -1.0,   max = 1.0 )         (Note 1)
                  norm1(<data>, <n>)    ( => mean =  0.0              )
                  norm2(<data>, <n>)    ( => mean =  0.0, sigma = 1.0 )         (Note 2)
                  norm3(<data>, <n>)    ( =>  sum =  1.0              )         (Note 3)

                  where <data> is an array of double,
                        <n>    is the size of the array.

     If an error is detected, no data is processed.

                  Note 1:       If the data is constant,   data is zeroed
                  Note 2:       If the data is constant,  sigma is kept to 0.0
                  Note 3:       If the sum of data is zero, sum is kept to 0.0

Documentation in '..\Resource\now.hdr'

     Macro function NOW(<parm>)  returning a long integer, where  <parm> is "year", "month", "day", "hour", "minute" or "second"

     And these macros below defining long integer constants replace advantageously the function NOW() ;

       THIS_YEAR         2011..
       THIS_MONTH        1..12
       THIS_DAY          1..31
       THIS_HOUR         0..23
       THIS_MINUTE       0..59
       THIS_SECOND       0..59

     NB: TIME IS PICKED ONCE DURING THE SIMULATION, results are then presented on demand <<<<<

Documentation in '..\Resource\number.hdr'

      Break a number as    sign * mantissa* POW10(range)

     'number_sign(x)'          -1.0, 0.0, 1.0
     'number_mantissa(x)'      [0.0 .. 1.0[
     'number_range(x)'         [0.0 .. Inf[

      Build a number as    sign * mantissa* POW10(range)

     'make_number(sign, mantissa, range)'

     Examples

       -1234.56789
        number_sign    (-1234.56789)          ->   -1
        number_mantissa(-1234.56789)          ->    0.123456789
        number_range   (-1234.56789)          ->    4
        make_number    (-1, 0.123456789, 4)   ->   -1234.56789

Documentation in '..\Resource\number3.hdr'

      number3(n) : for a better readability, format integer number in a string grouping by 3 digits separated by a spacing.

     Example:     number3(1234567890)  ->  "1 234 567 890"

Documentation in '..\Resource\pathname.hdr'

     User function 'shorten_pathname(pathname, n)'
        Reduce the length of a pathname if larger than n, to be used when producing a message (error, warning, debug...).
        This new pathname could be an abbreviation (dropping part of the pathname) and therefore may be not syntactically correct.

     User function 'simplify_pathname(pathname)'
        Delete useless complexity of pathnames.

                 Before                         After

                  /foo/                ->       /foo
                  /foo/../../bar       ->       /bar
                  /foo/./blah/..       ->       /foo
                  .                             .
                  ..                            ..
                  ./foo                ->       foo
                  foo/../../../bar     ->       ../../bar

Documentation in '..\Resource\PFD.hdr'

      Collection of PFD modules for user function 'dpll':  2 to 7 states PFD description.
      Positive feedback (type 2, 3, ..., 7) or negative feedback (-2 , -3, ..., -7) PFDs.

      It is possible to point to another file (see documentation in file "../User/dpll.hdr")

     PFD STATE MACHINES    POSITIVE FEEDBACK type: 2, 3, 4, 5, 6, 7  or  NEGATIVE FEEDBACK type: -2,-3,-4,-5,-6,-7

      R:     1 for a positive transition of the reference clock
      F:     1 for a positive transition of the feedback clock

      type '2', POSITIVE FEEDBACK
            ____________       ____________
           |            | R   |            |
       +-->|            |---->|            |---+
     F |   | state -1   |     | state  1   |   | R
       +---|            |<----|            |<--+
           |____________|   F |____________|

      type '3', POSITIVE FEEDBACK
            ____________       ___________       ____________
           |            | R   |           | R   |            |
       +-->|            |---->|           |---->|            |---+
     F |   | state -1   |     |  state 0  |     | state  1   |   | R
       +---|            |<----|           |<----|            |<--+
           |____________|   F |___________|   F |____________|

      ...

      type 'n', POSITIVE FEEDBACK

            ____________       ____________       _    _       ____________       ___________
           |            | R   |            | R   |      | R   |            | R   |           |
       +-->|            |---->|            |---->|      |---->|            |---->|           |---+
     F |   | state -n   |     | state -n+1 |     |  ..  |     | state  n-1 |     | state  n  |   | R
       +---|            |<----|            |<----|      |<----|            |<----|           |<--+
           |____________|   F |____________|   F |_    _|   F |____________|   F |___________|

      type '-2', NEGATIVE FEEDBACK
            ____________       ____________
           |            | F   |            |
       +-->|            |---->|            |---+
     R |   | state -1   |     | state  1   |   | F
       +---|            |<----|            |<--+
           |____________|   R |____________|

       type '-3', NEGATIVE FEEDBACK
            ____________       ___________       ____________
           |            | F   |           | F   |            |
       +-->|            |---->|           |---->|            |---+
     R |   | state -1   |     |  state 0  |     | state  1   |   | F
       +---|            |<----|           |<----|            |<--+
           |____________|   R |___________|   R |____________|

      ...

       type '-n', NEGATIVE FEEDBACK
            ____________       ____________       _    _       ____________       ___________
           |            | F   |            | F   |      | F   |            | F   |           |
       +-->|            |---->|            |---->|      |---->|            |---->|           |---+
     R |   | state -n   |     | state -n+1 |     |  ..  |     | state  n-1 |     | state  n  |   | F
       +---|            |<----|            |<----|      |<----|            |<----|           |<--+
           |____________|   R |____________|   R |_    _|   R |____________|   R |___________|

Documentation in '..\Resource\pisarenko.hdr'

     Pisarenko Harmonic Decomposition. This routine estimates the frequency of a single sinusoid despite white noise.

      freq = pisarenko(wave, numofpoints)

     To convert to physical frequency in Hz, result is multiplied by the sampling rate.
     The accuracy of the Pisarenko harmonic decomposition improves with collected data size and SNR.

     Prefer the routine in "freq.hdr" !

Documentation in '..\Resource\pluraltext.hdr'

       How to print proper plurals

       PLURAL_TEXT1(n)      for plural in 's'
       PLURAL_TEXT2(n)      for plural in 'es'

       Other plurals are not currently supported, sorry!

       Usage:          fprintf(stdout, "%d thing%s in %d box%s\n", i, PLURAL_TEXT1(i), i, PLURAL_TEXT2(i));

Documentation in '..\Resource\pointer.hdr'

     Macro function 'CHECK_POINTER(p)' to be used to test if a pointer is defined.
     Use to debug header files.

     Triggered by  'debug POINTER'

Documentation in '..\Resource\polygon.hdr'

     Function 'polygon_area(n, v)'  returns area of the polygon. The polygon has n vertices. 'v' contains 2*n double float numbers

     NB: For this technique to work, the polygon must not be self intersecting.

         The vertices must be ordered according to positive or negative orientation (counterclockwise or clockwise, respectively);
         if they are ordered negatively, the value given by the area formula will be negative but correct in absolute value.
         This is commonly called the Shoelace formula or Surveyor's formula.

         The sign of the area expression can therefore be used to determine the ordering of the vertices of the polygon.

                    8 . . . . . . . D* * * *C
     Example:                     *            *
                    7           *                 *              6 Vertices
                      . . . . E                      *
                    6         .*                        *
                              . *                          *
                    5 . . . . . .*                            B
                              .   *       (Polygon)          *.
                    4 . . . . . . .*                        * .
                              .     *                      *  .
                    3         .     .*                    *   .
                              .     . *                  *    .
                    2         .     .  *                *     .
                      . . . . . . . . . F* * * * * * * A      .
                    1         .     .   .   .          .      .
                              .     .   .   .          .      .
                    0----1----2----3----4----5----6----7----8----9----

         ...
         double   area;
         double **v = (double**) NULL;
         ...
         (void) DA2_MANAGER(ALLOCATE, &v, 6, 2, "polygon");             <-- 2D array of  (6x2)  double float numbers
         ...
         v[0,0] = 7.0;  v[0,1] = 1.5;                                   <-- Vertex  'A'  ((0,0), (0,1))
         v[1,0] = 8.4;  v[1,1] = 5.0;                                   <-- Vertex  'B'  ((1,0), (1,1))
         v[2,0] = 4.8;  v[2,1] = 8.0;                                   <-- Vertex  'C'  ((2,0), (2,1))
         v[3,0] = 3.2;  v[3,1] = 8.0;                                   <-- Vertex  'D'  ((3,0), (3,1))
         v[4,0] = 2.0;  v[4,1] = 7.5;                                   <-- Vertex  'E'  ((4,0), (4,1))
         v[5,0] = 4.0;  v[5,1] = 1.5;                                   <-- Vertex  'F'  ((5,0), (5,1))

         area   = polygon_area(6L, c);
         ...
         (void) DA2_MANAGER(FREE,     &v, 6, 2, "polygon");
         ...

Documentation in '..\Resource\polynomial.hdr'

     Evaluation of a Polynomial  (using Horner Scheme)

               y = c[0] + c[1]*x + c[2]*x^2 + .. + c[n]*x^n

       USAGE:  y = polynomial(x, n, c*)

       where   double x             input
               long   n             input:  order of the polynomial         n >= 0
               double c[n+1]        input:  coefficients of the polynomial  0 .. n
               double y            output:  value of polynomial

Documentation in '..\Resource\polynom_derivate.hdr'

     Symbolic Derivation of a Polynomial.

               polynom_derivate(c[0] + c[1]*x + .. + c[n]*x^n, x)

       USAGE:  order = polynom_derivate(n, c*)

       where   long   order        output:  effective order of the resulting Polynomial
               long   n             input:  order of the input Polynomial
               double c[n+1]        input:  coefficients of the Polynomial  0 .. n.
                               and output:  coefficients of the Polynomial after derivation

       This function modifyes the Polynomial and returns the degree of the Polynomial after derivation.

     Effective Degree of a Polynomial.

               polynom_degree(c[0] + c[1]*x + .. + c[n]*x^n, x)

       USAGE:  order = polynom_degree(n, c*)

       where   long   order        output:  effective order of the resulting Polynomial
               long   n             input:  order of the input Polynomial
               double c[n+1]        input:  coefficients of the Polynomial  0 .. n.

Documentation in '..\Resource\poolbuf.hdr'

      function poolbuf(str)

      This function allows to submit strings in a 'printf', 'fprintf'... without conflicts of memory.
      To be used to return safely a string built inside a function.

      Example:      char *afunction(int n) 
                      char astring[32];
                      ...
                      return poolbuf(astring);

                    ...
                    void fprintf(stdout, "a string '%s' and another string '%s'\n", afunction(123), afunction(987));
                    ...

Documentation in '..\Resource\print_bits.hdr'

     Function print_bits(<fp>,<num>) prints the number as a sequence of bits (no carriage return)

         where <fp>  is a file handler
               <num> is the long long integer to print

Documentation in '..\Resource\print_current_directory.hdr'

     Function 'print_current_directory(fptr)'                                    /* Compatible only for the 'gcc' compiler

Documentation in '..\Resource\print_polynomial.hdr'

     Function      print_polynomial()

     USAGE:        print_polynomial(n, N*, d, D*, "letter")

                   when d == 0, a polynomial in power of <"letter"> is printed
                   when d != 0, num and den polynomials in power of <"letter"> are printed

     Check <n> and <d> to avoid memory leakage!!!

Documentation in '..\Resource\psophometric.hdr'

      Psophometric weighting in frequency domain.

      A noise weighting established by the International Consultative Committee for Telephony (CCIF, which became CCITT and, more
      recently, ITU-T), designated as CCIF-1951 weighting, for use in a noise measuring set or psophometer.

      ITU-T Recommendation O. 41: 1994

Documentation in '..\Resource\pz.hdr'

     extract_and_print_PZ()    Extract & Print Poles and Zeroes of a Laplace Domain Transfer Function.

             N0 + N1*s + N2*s^2 .. + Nn*s^(n-1)
      H(s) = ----------------------------------
             D0 + D1*s + D2*s^2 .. + Dd*s^(d-1)

     Where parameters (N0 .. Nn) and (D0 .. Dd) are constant real numbers.

     USAGE:    extract_and_print_PZ(n, N*, d, D*)

        where  long   n                input: number of coefficients of numerator
               double N[]              input: coefficients of the numerator
               long   d                input: number of coefficients of denominator
               double D[]              input: coefficients of the denominator

Documentation in '..\Resource\quinn.hdr'

     QUINN'S Second Estimator
     Estimate the frequency of a signal around its FFT peak.

     USAGE: freq = quinn2(re, in, k, np)

     where re and im are respectively pointers to FFT real and imaginary tables
           k    is the index corresponding to the maximum of the signal in the FFT table
           np   is the size of the FFT table
           freq is the interpolated value corresponding to the best estimate of frequency

     Depends on the local sampling frequency FSL

Documentation in '..\Resource\rand_char.hdr'

     Functions rand_char(), rand_name() and macros RAND_CHAR(), RAND_NAME()

     rand_char(s, lst)
         this function fills an existing string variable, 's' being its pointer, with random alphanumeric characters randomly from
         the characters of the string constant 'lst'.

     rand_name(s, pre, lst)
         this function fills an existing string variable, 's' being its pointer, with a prefix 'pre' followed by alphanumeric
         characters randomly chosen from the characters of the string constant 'lst'.

     RAND_CHAR(s)
         this macro fills an existing string variable, 's' being its pointer, with random alphanumeric characters randomly
         chosen from the string macro 'RAND_CHAR_LIST' containing the set of alphanumeric characters.

     RAND_NAME(s, pre)
         this macro fills an existing string variable, 's' being its pointer, with a prefix 'pre' followed by alphanumeric
         characters randomly chosen from the string 'macro RAND_CHAR_LIST' containing the set of alphanumeric characters.

     directive RAND_CHAR_LIST "..."    redefines the set of characters used in macros RAND_CHAR() and RAND_NAME()

Documentation in '..\Resource\read.hdr'

     macros  RESET_READ_EOF_FLAG(), SET_READ_EOF_FLAG()
     these macros trigger flags to help to control the simulation and end of file warning message

     Use flag  READ_EOF_FLAG  to control the end of a simulation through NAPA instruction 'terminate'

Documentation in '..\Resource\recaman.hdr'

      Recaman sequence:   recamansequence(N)     prints the N first elements of the Recaman sequence

     The sequence satisfies:  r(n) >= 0  and  |r(n) - r(n-1)| = n
     It takes its name after its inventor Bernardo Recamán Santos, a Colombian mathematician.

     This is not a permutation of the integers: the first repeated term is 42 = r(24) and r(20)  and  43 = r(18) and r(26)
     Neil Sloane has conjectured that every number eventually appears, but it has not been proved. Even though 10^230 terms have
     been calculated in 2018, the number 852655 has not appeared on the list.

Documentation in '..\Resource\register_width.hdr'

     Register Arithmetic   adjust_register_width()     to mimic the behavior of a limited width register

     USAGE   <out> = adjust_register_width( <in>, <width> )

       where <out> is the integer number <in> truncated in a register with a number of bits <width>
           <width> is positive:  unsigned integer rolloff      in a NAPA netlist, it is corresponding to the syntax   <n> ivar ...
                      negative:    signed integer rolloff      in a NAPA netlist, it is corresponding to the syntax   (n) ivar ...
                      zero    :              no operation

       Example of register arithmetic with limied register width

           3 bits  ->  2 complement code of        |      3 bits  ->  unsigned code of
              000                         0        |         000                     0
              001                         1        |         001                     1
              010                         2        |         010                     2
              011                         3        |         011                     3
              100                        -4        |         100                     4
              101                        -3        |         101                     5
              110                        -2        |         110                     6
              111                        -1        |         111                     7
              000                         0        |         000                     0
              001                         1        |         001                     1
              ...                       ...        |         ...                   ...

Documentation in '..\Resource\s.hdr'

       This subheader allocates and defines SINE arrays.
       The idea is to create a minimum of arrays in an efficient way, saving time and memory allocation and optimize reuse of
       tables. Process is transparent for calling function.

       USAGE:   S_MANAGER(ALLOCATE, &sintable,  number, tag)
                S_MANAGER(FREE,     &sintable,  number, tag)
                S_MANAGER(QUERY,    &sintable,  number, tag)

       Returns the number of elements allocated (long integer).

       Where '&sintable' is the address of array of double and 'number' is the number of samples in a sine period. Memory is
       allocated and address is returned back (ALLOCATE), or memory is desallocated and NULL address returned back (FREE).  Size
       of memory allocated can be obtained (QUERY). 'tag' is a string identifying the tool being used.

       Related functions: see also C_MANAGER() and SC_MANAGER()

Documentation in '..\Resource\sarc4link.hdr'

      This header is included in the duser function 'sarc' to guarantee the link of the SARC engine to the simulator.

Documentation in '..\Resource\savitzki_golay.hdr'

     Savitzki-Golay Smoothing Filter Coefficients Generator

     Function  savitzki_golay(coef, len, nleft, nright, m, order)

       returns coef[0, len-1], the set of Savitzky-Golay filter coefficients.

       where  len     is the number of elements of coef[]
              nleft   is the number of leftward  (past)   data points used
              nright  is the number of rightward (future) data points used
              m       is the order of the smoothing polynomial, and is equal to the highest conserved moment
                      [usual values are m = 2 or m = 4]
              order   is the order of the derivative desired
                      [for data fitting, order = 0]

       ->   len    cannot be smaller than (nleft+nright+1), the number of data points used
       ->   nleft  must be positive
       ->   nright must be positive
       ->   m      must be positive, cannot be larger than (nleft+nright)
       ->   order  must be positive, cannot be larger than  m

                         Samples of Savitzky-Golay Coefficients with order = 0

     index      -5     -4     -3     -2     -1      0      1      2      3      4      5
                                                    |
     nl nr m                                        |
                                                    |
     2  2  2                       -0.086  0.343  0.486  0.343 -0.086
     3  1  2                -0.143  0.171  0.343  0.371  0.257
     4  0  2          0.086 -0.143 -0.086  0.257  0.886
     5  5  2  -0.084  0.021  0.103  0.161  0.196  0.207  0.196  0.161  0.103  0.021 -0.084
     4  4  4          0.035 -0.128  0.070  0.315  0.417  0.315  0.070 -0.128  0.035
     5  5  4   0.042 -0.105 -0.023  0.140  0.280  0.333  0.280  0.140 -0.023 -0.105  0.042
                                                    |

     Example of output of this function (refer to indexes of table above):

      nleft = 3, nright = 1, m = 2, order = 0     therefore the number of coefficients is  len = (nleft+nright+1) = 5

     savitzki_golay(coef, 5, 3, 1, 2, 0)
                coef[0] =  0.371429      <-  index  0
                coef[1] =  0.342857      <-  index -1
                coef[2] =  0.171429      <-  index -2
                coef[3] = -0.142857      <-  index -3
                coef[4] =  0.257143      <-  index  1

Documentation in '..\Resource\sc.hdr'

       This subheader allocates and defines SINE/COSINE arrays used by FFT based tools.
       Sine and Cosine tables are used by the FFT algorithm but the same tables are used also by the windowing functions.
       The idea is to create a minimum of arrays in an efficient way, saving time and memory allocation and optimize reuse of
       tables. Process is transparent for calling function.

       USAGE:   SC_MANAGER(ALLOCATE, &sintable, &costable, number, tag)
                SC_MANAGER(FREE,     &sintable, &costable, number, tag)
                SC_MANAGER(QUERY,    &sintable, &costable, number, tag)

       Returns the number of elements allocated (long integer).

       Where '&sintable' and '&costable' are addresses of array of double and 'number' is the number of samples in a sine/cosine
       period. Memory is allocated and addresses are returned back (ALLOCATE), or memory is desallocated and NULL addresses
       returned back (FREE).  Size of memory allocated can be obtained (QUERY).
       'tag' is a string identifying the tool being used.

       Related functions: see also S_MANAGER() and C_MANAGER()

Documentation in '..\Resource\scaling.hdr'

     A few Scaling Factors

        yocto ( _y)     zepto ( _z)     atto ( _a)     femto ( _f)     pico ( _p)     nano ( _n)     micro ( _u)     milli ( _m)
        kilo  ( _k)     mega  ( _M)     giga ( _G)     tera  ( _T)     peta ( _P)     exa  ( _e)     zeta  ( _Z)     yotta ( _Y)

        kibi  (_ki)     mebi  (_Mi)     gibi (_Gi)     tebi  (_Ti)     pebi (_Pi)     exbi (_Ei)     zebi  (***)     yobi  (***)

        NB:  (***)      these factors are not defined here as they overflow I_TYPE !

Documentation in '..\Resource\shuffle.hdr'

     Shuffle a list of indexes (long integers).

     USAGE:   shuffle(listofindexes, num, "mylist")

       where  <listofindexes> is a pointer to a list of numbers or to the indexes of a table of elements
              <num>           is the number of elements of the table
              <"mylist">      is the name to be displayed as information when debugging

     It generates all permutations of the list with equal probability.

     The directive 'debug SHUFFLE' triggers the output of a debug information table.

     Check the number of indexes <num> to avoid memory leakage!!!

Documentation in '..\Resource\sigmoid.hdr'

     Functions 'logistic(t, m, n, tau)'                Generalised Logistic Function
     Function  'sigmoid(t)'                            Sigmoid
     Function  'sigmoid_p(t)'                          Sigmoid'

        sigmoid (t) = logistic(t, 0.0, 1.0, 1.0)
        sigmoid'(t) = sigmoid(t)*(1.0-sigmoid(t))

Documentation in '..\Resource\sign.hdr'

     Function 'sign(x)',  the sign function

     This function returns   -1    if x <  0.0
                              0    if x == 0.0
                             -1    if x >  0.0

     Equivalent to cmp3(x, 0.0),                           see file "./cmp3.hdr"

Documentation in '..\Resource\slope.hdr'

     lin_slope()
     straight line tangent to tanh() function in 0, clipping at -1 and 1

     sin_slope()
     sinewave line tangent to tanh() function in 0, clipping at -1 and 1

     exp_slope()
     damped exponential tangent to tanh() function in 0, clipping at -1 and 1

                       y
                       .   __________  +1
                       .  /
                       . /                      y = lin_slope(x)
                       ./
           ............................. x
                      /.
                     / .
         -1 ________/  .

Documentation in '..\Resource\slowprintf.hdr'

     slowprintf(string, nseconds) doesn't put a string on 'stderr' immediately, but smoothly, letter after letter.

Documentation in '..\Resource\smith.hdr'

     Functions to compute the Smith Chart     smithR_x(r, t), smithR_y(r, t),      t in [0, 2Pi]
                                              smithX_x(x, t), smithX_y(r, t),      t in [0, 2Pi]

     Wikipedia:
       The Smith chart, invented by Phillip H. Smith (1905–1987),is a graphical aid or nomogram designed for electrical and
       electronics engineers specializing in radio frequency (RF) engineering to assist in solving problems with transmission
       lines and matching circuits.The Smith chart can be used to simultaneously display multiple parameters including impedances,
       admittances, reflection coefficients, Snn scattering parameters, noise figure circles, constant gain contours and regions
       for unconditional stability, including mechanical vibrations analysis. The Smith chart is most frequently used at or within
       the unity radius region. However, the remainder is still mathematically relevant, being used, for example, in oscillator
       design and stability analysis.

Documentation in '..\Resource\sort_strings.hdr'

     Function 'sort_strings(n, str)'
        sorts the list of strings 'str' in alphabetical order

Documentation in '..\Resource\sound.hdr'

     Macro    'SPEED_OF_SOUND(T)'

        Returns the speed of sound (m/s), function of the temperature (K)
        Good accuracy in [-100°C, 100°C] temperature range   (see reference)

Documentation in '..\Resource\spline.hdr'

     Macros used in spline interpolations.

     p = CATMULL_ROM_SPLINE     (mu, p0, p1, p2, p3);          0.0 <= mu <= 1.0    =>               p1 <= p <= p2
                                                                                   =>
     p = LINEAR_BEZIER_SPLINE   (mu, p0, p1);                  0.0 <= mu <= 1.0    =>               p0 <= p <= p1
     p = QUADRATIC_BEZIER_SPLINE(mu, p0, p1, p2);              0.0 <= mu <= 1.0    =>               p0 <= p <= p2
     p = CUBIC_BEZIER_SPLINE    (mu, p0, p1, p2, p3);          0.0 <= mu <= 1.0    =>               p0 <= p <= p3
                                                                                   =>
     p = CUBIC_B_SPLINE         (mu, p0, p1, p2, p3);          0.0 <= mu <= 1.0    =>   (p0+4*p1+p2)/6 <= p <= (p1+4*p2+p3)/6
     p = DOUBLE_CUBIC_B_SPLINE  (mu, p0, p1, p2);              0.0 <= mu <= 1.0    =>      (p0+5*p1)/6 <= p <= (p2-5*p1)/6
     p = QUADRATIC_B_SPLINE     (mu, p0, p1, p2);              0.0 <= mu <= 1.0    =>        (p0+p1)/2 <= p <= (p1+p2)/2
                                                                                   =>

     Functions used in spline interpolations.

     p = catmull_rom_spline     (mu, p0, p1, p2, p3);          0.0 <= mu <= 1.0    =>               p1 <= p <= p2
                                                                                   =>
     p = linear_bezier_spline   (mu, p0, p1);                  0.0 <= mu <= 1.0    =>               p0 <= p <= p1
     p = quadratic_bezier_spline(mu, p0, p1, p2);              0.0 <= mu <= 1.0    =>               p0 <= p <= p2
     p = cubic_bezier_spline    (mu, p0, p1, p2, p3);          0.0 <= mu <= 1.0    =>               p0 <= p <= p3
                                                                                   =>
     p = cubic_b_spline         (mu, p0, p1, p2, p3);          0.0 <= mu <= 1.0    =>   (p0+4*p1+p2)/6 <= p <= (p1+4*p2+p3)/6
     p = double_cubic_b_spline  (mu, p0, p1, p2);              0.0 <= mu <= 1.0    =>      (p0+5*p1)/6 <= p <= (p2-5*p1)/6
     p = quadratic_b_spline     (mu, p0, p1, p2);              0.0 <= mu <= 1.0    =>        (p0+p1)/2 <= p <= (p1+p2)/2
                                                                                   =>

     NB: for 2D control points P0x,P0y, P1x,P1y, ..., interpolate 'x' coordinates with P0x, P1x, ... using one of these
         functions and 'y' coordinates with P0y, P1y, ... using the same function.

     The Catmull-Rom spline has the following characteristics:
      - The spline passes through all of the control points.
      - The spline is C1 continuous, meaning that there are no discontinuities in the tangent direction and magnitude.
      - The spline is not C2 continuous.  The second derivative is linearly interpolated within each segment,
        causing the curvature to vary linearly over the length of the segment.
      - On a segment may lie outside of the domain of p1 -> p

Documentation in '..\Resource\sqroot.hdr'

      Square root function of an integer:  sqroot(n)

Documentation in '..\Resource\stack.hdr'

     Macros to create and manage a stack inside a C function.

     Stack structures:  LONG_STACK
                        UNSIGNED_LONG_STACK
                        DOUBLE_STACK

     USAGE:             STACK_CLEAR(my_stack)              returns 0
                        STACK_PUSH(my_stack, element)      returns element  or  0 (fail)
                        STACK_POP(my_stack)                returns element  or  0 (fail)
                        STACK_PEEK(my_stack)               returns element  or  0 (fail)
                        STACK_POINTER(my_stack)            returns value of stack pointer

     'directive STACK_SIZE nn' adjusts the max number of elements on stacks (default 100)
     'directive CALC_STACK_SIZE nn' adjusts the number of elements on stacks (default 100)

      NB: A structure of type LONG_STACK, UNSIGNED_LONG_STACK or DOUBLE_STACK must be declared

Documentation in '..\Resource\stirling.hdr'

      Stirling Correction

      Correction term of the Stirling approximation for log(k!), (series in 1/k, or table values for small k).

      log k! = (k + 1/2)log(k + 1) - (k + 1) + (1/2)log(2Pi) + StirlingCorrection(k + 1)
      log k! = (k + 1/2)log(  k  ) -    k    + (1/2)log(2Pi) + StirlingCorrection(  k  )

Documentation in '..\Resource\string.hdr'

     Macro function 'STRINGIFY(x)'                  to be used for stringification.
     Macro function 'BEGINOFSTRING(str)'            pointer to begin of string.
     Macro function 'ENDOFSTRING(str)'              pointer to end of string.

     Macro function 'ISEMPTY(str)'                  test if the string is empty.
     Macro function 'ISNOTEMPTY(str)'               test if the string is not empty.

     Function 'clean_stringification(str)'          to be used to remove extar quotes after stringification.
     Function 'compact_string(str)'                 removes extra spaces.
     Function 'join_2_strings(str1, str2)'          the 2 strings are concatenated.
     Function 'join_3_strings(str1, str2, str3)'    the 3 strings are concatenated.
     Function 'extract_line(str1, str2)'            string before a \n (or \\n) is extracted, returns pointer to the string after

     Function 'replace_string(str, orig, rep)'      replace 'orig' string by 'rep' string, result in 'str'.

Documentation in '..\Resource\subfactorial.hdr'

     Function 'subfactorial(n)'   with n > 0

     The subfactorial (also called the derangement number) is the number of permutations of objects in which no object appears
     in its natural place (i.e. "derangements").

Documentation in '..\Resource\swapbytes.hdr'

     Endianess!

     Custom byte swap macros are used to wrap and standardize the code for accessing each data.
     Here are the byte swap macros for each data size.

       SwapTwoBytes()
       SwapFourBytes()
       SwapEightBytes()

       ***** 16 bit Big-Endian data        MY_RD_BE_SHORT MY_WRT_BE_SHORT

             #if BIG_ENDIAN == CPU_ARCHITECTURE
             Do nothing
             #else
             SwapTwoBytes (data)
             #endif

       ***** 16 bit Little-Endian data      MY_RD_LE_SHORT MY_WRT_LE_SHORT

             #if BIG_ENDIAN == CPU_ARCHITECTURE
             SwapTwoBytes (data)
             #else
             Do nothing
             #endif

       ***** 32 bits Big-Endian data      MY_RD_BE_LONG MY_WRT_BE_LONG

             #if BIG_ENDIAN == CPU_ARCHITECTURE
             Do nothing
             #else
             SwapFourBytes (data)
             #endif

      ***** 32 bits Little-Endian data    MY_RD_LE_LONG MY_WRT_LE_LONG

            #if BIG_ENDIAN == CPU_ARCHITECTURE
            SwapFourBytes (data)
            #else
            Do nothing
            #endif

     *****  64 bits Big-Endian data      MY_RD_BE_DOUBLE MY_WRT_BE_DOUBLE

            #if BIG_ENDIAN == CPU_ARCHITECTURE
            Do nothing
            #else
            SwapEightBytes (data)
            #endif

     *****  64 bits Little-Endian data    MY_RD_LE_DOUBLE MY_WRT_LE_DOUBLE

            #if BIG_ENDIAN == CPU_ARCHITECTURE
            SwapEightBytes (data)
            #else
            Do nothing
            #endif

       Macro Code 16 bits:    SwapTwoBytes(data)

       Macro Code 32 bits :   SwapFourBytes(data)

       Macro Code 64 bits:    SwapEightBytes(data)

Documentation in '..\Resource\symmetry.hdr'

     check for the symmetry of a list of data  (long long or double)

     Functions:   out = check_for_symmetry_d(list, n)           where <n> is index max in the list
     Functions:   out = check_for_symmetry_i(digital,list, n)   where <n> is index max in the list

      return     0   for   assymmetry
                 1   for     symmetry
                -1   for antisymmetry

     Check the index <n> to avoid memory leakage!!!

      n = 9    symmetric     antisymmetric    assymetric

      0   ->           a                 a             a
      1   ->           b                 b             b
      2   ->           c                 c             c
      3   ->           d                 d             d
      4   ->           e                 e             e
      5   ->           e                -e             f
      6   ->           d                -d             g
      7   ->           c                -c             h
      8   ->           b                -b             i
      9   ->           a                -a             j

Documentation in '..\Resource\synchro.hdr'

     Definition of the synchronization macro 'SYNCHRO_SWEEP' for user functions to be synchronized.

Documentation in '..\Resource\time.hdr'

     Function 'time2ASCII(..)'             millisecond resolution, format ISO 8601 compliant
     Function 'slim_time2ASCII(..)'        millisecond resolution

     Example:     (void) fprintf(stdout, "... %s ...\n", time2ASCII(WALL_CLOCK));

Documentation in '..\Resource\token.hdr'

     Functions 'get_token()', 'get_fat_token()', 'swallow_token()'
               'get_nth_token()', 'swallow_n_token()'

                where separators are spaces ( ' ', '\t', '\n' )

        'get_token(str, tok)'          gets the 1st token of a string
        'get_fat_token(str, tok)'      gets the 1st token of a string including the preceding spaces
        'swallow_token(str)'           swallows 1 token of a string
        'get_nth_token(str, tok, N)'   gets the Nth token of a string   (N = 1..)
        'swallow_n_token(str, N)'      swallows N tokens of a string    (N = 1..)
        'token_count(str)'             count the number of tokens separated by blank(s) in string

     USAGE:      char* str;
                 char  tok[16];
                 char  buf[32] = "Mary Had a Little Lamb";
                 ...
                 str = buf;
                 str = get_token(str, tok);
                 str = get_fat_token(str, tok);

         At this point,

        'buf' still contains the string "Mary Had a Little Lamb"
        'str' points now to the 1st character of the substring  "a Little Lamb"
        'tok' contains the token " Had"

                 ...
                 str = swallow_token(str);

         At this point,

        'buf' still contains the string "Mary Had a Little Lamb"
        'str' points now to the 1st character of the substring  "Little Lamb"

Documentation in '..\Resource\triangle.hdr'

     Function 'triangle_area(xa, ya, xb, yb, xc, yc)'  returns area of the triangle.
     Depending on the order of the vertices, the result can be negative.

Documentation in '..\Resource\trig.hdr'

     normalize_radians(), normalize_degrees(), reduce the input to the first trigonometric circle [-PI, PI].

     In addition, radians_to_degrees(), degrees_to_radians() makes the conversion

Documentation in '..\Resource\trim.hdr'

     Function 'ltrim(str, trim)'                    strip leading characters of 'trim' from 'str'.
     Function 'rtrim(str, trim)'                    strip trailing characters of 'trim' from 'str'.

Documentation in '..\Resource\twist.hdr'

     Twist 2 wires

     USAGE:

       twist_d(out1, out0, in1, in0, ctr)                <-  analog
       twist_i(out1, out0, in1, in0, ctr)                <-  digital
       twist_b(out1, out0, in1, in0, ctr)                <-  bit

       ctr = true        in1 -> out1,  in0 -> out0
       ctr = false       in1 -> out0,  in0 -> out1

                 ctr
              ____|____
             |         |
       in1 --| - -1- -  >-- out1
             |   \ /   |
             |    0    |
             |   / \   |
       in0 --| - -1- -  >-- out0
             |_________|

Documentation in '..\Resource\unique.hdr'

     Function 'unique_name(<suffix>)'

     This function creates a unique string name completed by a suffix. This suffix, if any, is preceded by a '.'

     USAGE:

          char tok[64];
          (void) strcpy(tok, unique_name("out"));
          fprintf(stderr, "  < %s >\n", unique_name(""));
          fprintf(stderr, "  < %s >\n", tok);
          fprintf(stderr, "  < %s >\n", unique_name(".tmp"));

             < Uyl18524598172 >
             < Uyl18524598171.out >
             < Uyl18524598173.tmp >

Documentation in '..\Resource\variance.hdr'

     Functions 'compute_mean(x, n)', 'compute_variance(x, n)' and 'compute_sigma(x, n)'
               where x is a pointer to an array of double, n is the number of data in the array.

     Algorithms for calculating variance play a major role in statistical computing.
     A key problem in the design of good algorithms for this problem is that formulas for the variance may involve sums of
     squares, which can lead to numerical INSTABILITY as well as to arithmetic OVERFLOW when dealing with large values.

Documentation in '..\Resource\version.hdr'

      USAGE:  check_napa_version("<version_id>")

              Check that version of file is OLDER than current version of NAPA compiler.
              Exit on error.

              Goal is to identify simulation netlist older than current NAPA compiler

              example:   check_napa_version("V4.40d");

Documentation in '..\Resource\vincenty.hdr'

     Vincenty Inverse Solution of Geodesics on the Ellipsoid WGS-84, an oblate spheroidal earth.

     Calculate geodesic distance (in meters) between two points specified by latitude/longitude
     (in decimal degrees) using Vincenty inverse formula for ellipsoids.

         ********************************************************************
         *****   CAUTION!       UNDERSTAND SIGN CONVENTIONS!!!          *****
         ********************************************************************

     USAGE:   dist  = vincenty_distance(<lat1>, <lon1>, <lat2>, <lon2>)       [meters]

              where <lat1>, <lon1> are geodesic location of point 1  [decimal degrees]
              where <lat2>, <lon2> are geodesic location of point 2  [decimal degrees]

              distance computed according to the standard earth ellipsoid WGS-84.

     TIPS:  for latitude/longitude data, use tool like in    http://www.earthtools.org/

         *** CAUTION!  Signs convention:    Northern hemisphere    latitude  [+]
                                            Southern hemisphere    latitude  [-]
                                            Eastern  hemisphere    longitude [+]     <<<< Greenwich
                                            Western  hemisphere    longitude [-]     <<<<

     From wikipedia:

       The coordinate origin of WGS 84 is meant to be located at the Earth's center of mass, error is believed to be less than 2cm

       In WGS 84, the meridian of zero longitude is the IERS Reference Meridian. It lies 5.31 arc seconds east of the Greenwich
       Prime Meridian, which corresponds to 102.5 metres at the latitude of the Royal Observatory.

       Presently WGS 84 uses the 1996 Earth Gravitational Model (EGM96) geoid, revised in 2004. This geoid defines the nominal sea
       level surface by means of a spherical harmonics series of degree 360 (which provides about 100 km horizontal resolution).
       The deviations of the EGM96 geoid from the WGS 84 reference ellipsoid range from about -105 m to about +85 m. Note that
       EGM96 differs from original "WGS 84 geoid".

       As the distance is defined on an ellipsoid, there is no meaning to derive an angle.
       See functions in "lawofcosine.hdr and "haversine.hdr" for computation of angles.

Documentation in '..\Resource\week.hdr'

     Macros SUNDAY, .. SATURDAY              coded as 0, .. 6
     enum   weeksday    Sunday, .. Saturday
     Array of strings  daysoftheweek[7][10]

     Examples:   daysoftheweek[SUNDAY]  is the string "Sunday"
                 daysoftheweek[Sunday]  is the string "Sunday"
                 daysoftheweek[0]       is the string "Sunday"

Documentation in '..\Resource\windchill.hdr'

     Function 'windchill(Tambient,Vwind)'    Computes the new Windchill Temperature Index.  Use below 10°C

     where  Tambient  is the ambient temperature  (Kelvin)
            Vwind     is the speed of wind        (m/s   )

     The equation for an equivalent-temperature windchill index is accepted by Environment Canada and the US National Weather
     Service in 2001. It is important to note that the windchill is NOT a temperature in the strict sense but a temperature-like
     number that quantifies the sensation of cold. Thus, in Canada, it will be reported WITHOUT the degree designation.

Documentation in '..\Resource\window.hdr'

     Time Weigthing Functions, aka Windowing functions, for Fourier Transform.
     This subheader is used by functions of "fft0.hdr", "fft1.hdr",.. , "gft1.hdr",..

     Windows are calibrated vs power:   (input DC sig = 1.0)  =>  (sum of squared FFT values = 1.0)

     PLEASE NOTE:

       Windowing is mandatory for non coherent signals.
       Windowing could cause significant side effects.
       There is no good window. Window must be selected for the application.

       It is therefore important to understand why to use or not use a window.

     SIGWIDTH and DCWIDTH are related to the typical width of the window. Their default value is _WINWIDTH_ defined in windows.

         |
         |               .
         |\             / \
         | \           /   \
         |  \_________/  :  \_________________
         |               :
         |-->            |-->
          DCWIDTH         SIGWIDTH

     For rectangular window, we suppose that coherent sampling is used.

     Please understand that the width of the window is not necessarily corresponding to your application.
     Others values could be according to the specificity of the application.

      'directive DCWIDTH   <nnnn>'
      'directive SIGWIDTH  <nnnn>'

      'debug WINDOWING_INFO' triggers the output of debug information.

Documentation in '..\Resource\window2.hdr'

     Time Weigthing Functions, aka Windowing functions, for Lomb-Scargle Periodogram.
     This subheader is used by functions of "lsp0.hdr" and "lsp1.hdr".

     Windows are calibrated vs power (DC sig = 1.0 => mean value of squares = 1.0)

     SIGWIDTH and DCWIDTH are related to the typical width of the window. Their default value is _WINWIDTH_ defined in windows.

         |
         |               .
         |\             / \
         | \           /   \
         |  \_________/  :  \_________________
         |               :
         |-->            |-->
          DCWIDTH         SIGWIDTH

     Please understand that the width of the window is not necessarily corresponding to your application.
     Others values could be advantageously considered.

      'debug WINDOW_INFO' triggers the output of debug information.

Documentation in '..\Resource\winname.hdr'

     Available WINDOWS, using 'directive WINDOW one_of_this_name'

     ***  All windows here are defined 'periodic' and not 'symmetric'  ****

     DEFAULT                 alias of BLACKMAN_HARRIS_4
     NONE                    alias of RECTANGULAR

     BARTLETT
     BLACKMAN
     BLACKMAN_HARRIS         alias of BLACKMAN_HARRIS_4
     BLACKMAN_HARRIS_3
     BLACKMAN_HARRIS_4
     BLACKMAN_HARRIS_7
     BOXCAR                  alias of RECTANGULAR
     CONNES
     COSINE
     DE_LA_VALLEE_POUSSIN
     DIRICHLET               alias of RECTANGULAR
     EXACT_BLACKMAN
     EXACT_HAMMING
     FLAT_TOP                alias of FLAT_TOP_5
     FLAT_TOP_3
     FLAT_TOP_4
     FLAT_TOP_5
     GAUSSIAN
     HAMMING
     HANN                    alias of VON_HANN
     HANNING                 alias of VON_HANN
     HODIE                   alias of BLACKMAN_HARRIS_7
     HODIE_7                 alias of BLACKMAN_HARRIS_7
     KAISER_BESSEL           alias of KAISER_BESSEL_3
     KAISER_BESSEL_3
     MODIFIED_BARTLETT_HANNING
     NUTTALL
     RECTANGULAR
     ROSENFELD
     SQUARE                  alias of RECTANGULAR
     VON_HANN
     WELCH

Documentation in '..\Resource\wordwrap.hdr'

       Function 'wordwrap(buffer, string, line_width, indent_length)'

       This function takes a string and an output buffer and a desired width. It then copies the string to the buffer, indenting
       the text and inserting a new line character when a certain line length is reached. If the end of the line is in the middle
       of a word, it will backtrack along the string until white space is found.
       NO word could be larger than line_width. The buffer MUST be large enough !!!!

       Example:

       C code:

         char astring[] = "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed non risus.  [...]  egestas leo in pede.";
         char abuffer[1024];
         (void) wordwrap(abuffer, astring, 32, 5);
         (void) fprintf(stderr, "%s\n", abuffer);

       Output on screen :

         0         1         2         3         4
         .1234567890123456789012345678901234567890
         .
         .     Lorem ipsum dolor sit amet,
         .     consectetur adipiscing elit. Sed
         .     non risus. Suspendisse lectus
         .     tortor, dignissim sit amet,
         .     adipiscing nec, ultricies sed,
         .     dolor. Cras elementum ultrices
         .     diam. Maecenas ligula massa,
         .     varius a, semper congue, euismod
         .     non, mi. Proin porttitor, orci
         .     nec nonummy molestie, enim est
         .     eleifend mi, non fermentum diam
         .     nisl sit amet erat. Duis semper.
         .     Duis arcu massa, scelerisque
         .     vitae, consequat in, pretium a,
         .     enim. Pellentesque congue. Ut in
         .     risus volutpat libero pharetra
         .     tempor. Cras vestibulum bibendum
         .     augue. Praesent egestas leo in
         .     pede.

Documentation in '..\Resource\wrap.hdr'

      wrap(n, ilo, ihi) forces an integer to lie between given limits by wrapping.

      Example:   ilo = 4, ihi = 8

         i     wrap(i, 4, 8)

        -2                8
        -1                4
         0                5
         1                6
         2                7
         3                8
         4                4
         5                5
         6                6
         7                7
         8                8
         9                4
        10                5
        11                6
        12                7
        13                8
        14                4

Documentation in '..\Resource\zeta.hdr'

      Riemann zeta function of one and two arguments

      y = zeta(x)   == zeta2(x, 1.0)
      y = zeta2(x,q)
                               where x > 1 and q is not a negative integer or zero.

Documentation in '..\Resource\ztrans4link.hdr'

      This header is included in the duser function 'ztrans' to guarantee the link of the Z engine to the simulator.

Macros and Functions in code produced by the NAPA compiler

End