====== "sin" Sinusoidal time dependent value ======

===== Syntax =====

  sin args
  sin offset amplitude frequency delay damping

===== Purpose =====

The component value is a sinusoidal function of time, with optional exponential decay.

===== Comments =====

For voltage and current sources, this is the same as the Spice SIN function, with some extensions.

It generates either a steady sinusoid, or a damped sinusoid.

If //delay// and //damping// are both zero, you get a steady sine
wave at the specified //frequency//.  Otherwise, you get a damped
pulsed sine wave, starting after //delay// and damping out with a
time constant of 1/damping.

The shape of the waveform is described by the following algorithm:

<code>
reltime = time - _delay
if (reltime > 0.) {
  ev = _amplitude * sin(2*PI*_freq*reltime);
  if (_damping != 0.){
    ev *= exp(-reltime*_damping);
  }
  ev += _offset;
}else{
  ev = _offset;
}
</code>

For other components, it gives a time dependent value.

As an extension beyond Spice, you may specify the parameters as
name=value pairs in any order.

The non-Spice parameters (samples, zero, peak) assist in time step control.  The defaults are usually appropriate.
===== Parameters =====

|offset     |DC offset.  (Default = 0.)  |
|amplitude  |Peak amplitude.  (Default = 1.)  |
|frequency  |Frequency, Hz.  (required)  |
|delay      |Turn on delay, seconds.  (Default = 0.)  |
|damping    |Damping factor, 1/seconds.  (Default = 0.)  |
|samples    |Minimum number of samples per cycle.  (Default = 4)  |
|zero       |Flag: Synchronize internal time steps to zero crossings.  (Default = false)  |
|peak       |Flag: Synchronize internal time steps to peaks.  (Default = false)  |

===== Step control =====

For SIN, frequency is constant, so the default settings give preference to waveform smoothness over timing.

There is a smoothness requirement, controlled by the parameter "samples".  By default, there will be at least 4 samples per cycle.  This is independent of the placement of samples at zeros and peaks, but usually does not add samples.

If you set the parameters "zero" and "peak" to true, both zero crossings and peaks are considered to be analog events.  The transient analysis will attempt to control timing accuracy of these analog events.  If it is reasonable, a time step should be scheduled at these times exactly.  In any case, there should be a time step within option::dtmin of these times. These steps are forced regardless of steps required for smoothness.

"Zero" and "peak" are false by default, which allows time stepping to be more consistent, improving run speed.

If you need improved waveform smoothness, you can do this by increasing "samples".

If you need timing accuracy, set "zero" and/or "peak" to true.