Flexible magnet control scripting documentation

All magnet commands must be written inside a doMagnetFunction block.  The usage of that statement is:

doMagnetFunction( duration, @magnetFunction, parameter1, parameter2, ...)

• duration:  the duration, in seconds, that the specified magnetFunction should run
• magnetFunction:  one of a specially written selection of functions that generate values.  The list of functions is below.
• parameter1, parameter2, ...:  a number of parameters specific to the magnetFunction.  See below.

doMagnetFunction commands can be written one after another and will have the effect of concatenating the specified magnetFunctions.  They can also be enclosed in Matlab control structures such as for loops.

The following commands can be used in the scripting interface to the 3DFM magnet controls.

• magnetConstant:  specifies a constant output
  usage: doMagnetFunction( duration, @magnetConstant, value )
  • value:  the constant value generated
• magnetRamp:  from zero, linearly increase the output value over a specified time up to a specified value.  hold that value for a specified time.  linearly decrease the output value to zero over a specified time.
  usage: doMagnetFunction( duration, @magnetRamp, upValue, timeRampUp, timeUp, timeRampDown )
  • upValue:  the top, held value of the ramp.
  • timeRampUp:  the time over which the function ramps from zero to upValue.
  • timeUp:  the time the function holds the value at upValue.
  • timeRampDown:  the time over which the function ramps from upValue to zero.
• magnetSine:  a sinusoidal output of specified frequency, amplitude, phase and offset.
  usage: doMagnetFunction( duration, @magnetSine, amplitude, frequency, phase, offset )
  • this produces output of the form
    amplitude  * sin( 2* pi* frequency * time + phase ) + offset.
• magnetDeGauss:  an exponentially damped  sinusoidally varying function of specified frequency.
  usage: doMagnetFunction( duration, vStart, vEnd, frequency, duration )
  • vStart:  the initial (high) amplitude.
  • vEnd:  the final (low) amplitude.
  • frequency:  the frequency of the decaying sinusoid.
  • duration:  the time over which the amplitude of the sinusoid should decay from vStart to vEnd.  Note that duration appears twice.

Examples:

A slow sine wave between zero and two volts, lasting 60 minutes
doMagnetFunction( 3600, @magnetSine, 1, 0.1, 0, 1 );

Ten pulses of 2.5V lasting one second each, with two seconds in between.
for i = 1 : 10
doMagnetFunction( 1, @magnetConstant, 2.5 );
doMagnetFunction( 2, @magnetConstant, 0 );
end

Ten pulses with increasing voltage in 0.5V steps lasting one second with degauss pulses after each and then two second of zero force.  This is modeled on pole calibrations.
for i = 1 : 10
doMagnetFunction( 1, @magnetConstant, i * 0.5 );
doMagnetFunction( 0.1, @magnetDeGauss, i * 0.5, 0.001, 5000, 0.1 );
doMagnetFunction( 2, @magnetConstant, 0 );
end

A ramp increasing to two volts over half a second, held at two volts for three seconds, and decreasing immediately to zero; followed by a degauss and four seconds of zero force.  All this repeated for about an hour (note:  the duration of each pass is 7.6 seconds — 3.5 seconds for the ramp, plus 0.1 seconds for the degauss, plus 4 seconds of zero — so about 474 are needed to make up an hour).
for i = 1 :474
doMagnetFunction( 3.5, @magnetRamp, 2, 0.5, 3, 0 );
doMagnetFunction( 0.1, @magnetDeGauss, 3, 0.001, 5000, 0.1 );
doMagnetFunction( 4, @magnetConstant, 0 );
end
.