<?xml version="1.0" encoding="UTF-8"?>
<!--
This file is part of the Scilab time frequency toolbox.
This file must be used under the terms of the  terms of the GNU General Public License 
as published by the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

Copyright (c) 1996 by CNRS (France).
-->

<refentry xml:id="fmsin" xml:lang="en"
          xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:svg="http://www.w3.org/2000/svg"
          xmlns:scilab="http://www.scilab.org"
          xmlns:ns3="http://www.w3.org/1999/xhtml"
          xmlns:mml="http://www.w3.org/1998/Math/MathML"
          xmlns:db="http://docbook.org/ns/docbook">


  <refnamediv>
    <refname>fmsin</refname><refpurpose>Signal with sinusoidal frequency modulation.</refpurpose>
  </refnamediv>



  <refsynopsisdiv>
    <title>Calling Sequence</title>
    <synopsis>
      [Y,IFLAW]=fmsin(N)
      [Y,IFLAW]=fmsin(N,FNORMIN)
      [Y,IFLAW]=fmsin(N,FNORMIN,FNORMAX)
      [Y,IFLAW]=fmsin(N,FNORMIN,FNORMAX,PERIOD)
      [Y,IFLAW]=fmsin(N,FNORMIN,FNORMAX,PERIOD,T0)
      [Y,IFLAW]=fmsin(N,FNORMIN,FNORMAX,PERIOD,T0,FNORM0)
      [Y,IFLAW]=fmsin(N,FNORMIN,FNORMAX,PERIOD,T0,FNORM0,PM1)
    </synopsis>
  </refsynopsisdiv>

  <refsection>
    <title>Parameters</title>
    <variablelist>
      <varlistentry>
        <term>N  :</term>
        <listitem>
          <para>a positive integer:  number of points in time</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>FNORMIN :</term>
        <listitem>
          <para>a real scalar in [-0.5 0.5]: the smallest normalized frequency (default: 0.05)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>FNORMAX :</term>
        <listitem>
          <para>a real scalar in [-0.5 0.5]: the highest normalized frequency (default: 0.45)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>PERIOD  :</term>
        <listitem>
          <para>a positive scalar: the period of the sinusoidal fm (default: N   )</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>T0    :</term>
        <listitem>
          <para>an integer in [1 N]: the time reference for the phase(default: round(N/2)).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>FNORM0 :</term>
        <listitem>
          <para>a real scalar in [-0.5 0.5]: the highest normalized frequency (default: (FNORMAX+FNORMIN)/2)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>PM1     :</term>
        <listitem>
          <para>an integer value in {-1 +1}: the frequency direction at T0  (default: +1  )</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Y     :</term>
        <listitem>
          <para>a complex column vector of size N: the signal.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>IFLAW :</term>
        <listitem>
          <para>a real column vector of size N: the instantaneous frequency law (optional).</para>
        </listitem>
      </varlistentry>
      
    </variablelist>
  </refsection>

  <refsection>
    <title>Description</title>
    <para>
      fmsin generates a frequency modulation with a sinusoidal frequency.
      This sinusoidal modulation is designed such that the instantaneous
      frequency at time T0 is equal to FNORM0, and the ambiguity
      between increasing or decreasing frequency is solved by PM1.
    </para>
  </refsection>

  <refsection>
    <title>Examples</title>
    <programlisting role="example"><![CDATA[
    [X,IFLAW]=fmsin(140,0.05,0.45,100,20,0.3,-1.0);
    clf;
    subplot(211); plot(real(X));xtitle(_("Signal real part"))
    subplot(212); plot(IFLAW);xtitle(_("Instantaneous frequency law"))
   
    ]]></programlisting>
    <scilab:image><![CDATA[
    [X,IFLAW]=fmsin(140,0.05,0.45,100,20,0.3,-1.0);
    clf;
    subplot(211); plot(real(X));xtitle(_("Signal real part"))
    subplot(212); plot(IFLAW);xtitle(_("Instantaneous frequency law"))
    ]]></scilab:image>
  </refsection>

  <refsection>
    <title>See also</title>
    <simplelist type="inline">
      <member><link linkend="fmhyp">fmhyp</link></member>
      <member><link linkend="fmpower">fmpower</link></member>
      <member><link linkend="fmodany">fmodany</link></member>
      <member><link linkend="fmconst">fmconst</link></member>
      <member><link linkend="fmlin">fmlin</link></member>
      <member><link linkend="fmpar">fmpar</link></member>
    </simplelist>
  </refsection>

  <refsection>
    <title>Authors</title>
    <simplelist type="vert">
      <member>H. Nahrstaedt - Aug 2010</member>
      <member>F. Auger, July 1995.</member>
    </simplelist>
  </refsection>
</refentry>
