# Auto Compensation

## Functions
DLLEXPORT TECELLA_ERRNUM CALL | tecella_auto_offset (TECELLA_HNDL h, double jp_delta=0, int unused_stimulus_index=0)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_auto_comp_offset_adjust_mode_set (TECELLA_HNDL h, int channel, TECELLA_OFFSET_ADJUST_MODE mode)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_auto_comp_offset_adjust_mode_get (TECELLA_HNDL h, int channel, TECELLA_OFFSET_ADJUST_MODE *mode)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_auto_comp (TECELLA_HNDL h, double v_hold=0, double t_hold=20e-3, double v_step=10e-3, double t_step=20e-3, bool use_leak=true, bool use_digital_leak=false, bool use_cfast=true, bool use_cslow_a=true, bool use_cslow_b=true, bool use_cslow_c=true, bool use_cslow_d=true, bool use_artifact=true, double under_comp_coefficient=0.0, int acq_iterations=10, int unused_stimulus_index=0)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_auto_artifact_decay_start (TECELLA_HNDL h, double time_fraction)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_auto_artifact_update (TECELLA_HNDL h, double v_hold=0, double t_hold=19e-3, double v_step=10e-3, double t_step=19e-3, int iterations=10, int unused_stimulus_index=0)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_auto_artifact_enable (TECELLA_HNDL h, bool enable=true, int stimulus_index=0)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_auto_artifact_get_capacitance (TECELLA_HNDL h, int channel, double *capacitance)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_auto_artifact_get_size (TECELLA_HNDL h, int channel, int *size)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_auto_artifact_get (TECELLA_HNDL h, int channel, double *artifact, int max_size, int *actual_size)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_auto_artifact_set (TECELLA_HNDL h, int channel, double *artifact, int size)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_auto_frequency_boost_filter (TECELLA_HNDL h, int lpf_width, int stimulus=0)

## Detailed Description

Various functions are provided by the API to automatically compensate for junction potential offsets, leakage current, and unwanted capacitive spikes. Analog compensation is used when available. Then, digital compensations can be used to compensate anything the analog compensations may have missed.

## Function Documentation

DLLEXPORT TECELLA_ERRNUM CALL tecella_auto_artifact_decay_start | ( | TECELLA_HNDL | h,
|  | double | time_fraction |
| ) |  |  |

Lets the user indicate when artifact removal should start to linearly decay. Decaying earlier results in a smoother transition, but may not compensate faster capacitances as well.

Parameters:

  | h | A handle to an initialized device.
  | time_fraction | Must be within the range [0,1]. Represents a fraction of t_step in tecella_auto_artifact_update() at which artifact removal should start decaying.

DLLEXPORT TECELLA_ERRNUM CALL tecella_auto_artifact_enable | ( | TECELLA_HNDL | h,
|  | bool | enable = `true`,
|  | int | stimulus_index = `0` |
| ) |  |  |

Enables/disables the application artifact removal. Does nothing if tecella_auto_artifact() hasn't been called. Note: tecella_auto_comp() automatically disables artifact removal is any of the use_cfast or use_cslows are true and use_artifact is false.

Parameters:

  | h | A handle to an initialized device.
  | enable | Indicates if artifact removal should be turned on or off.
  | stimulus_index | For which stimulus to turn off artifact removal.

DLLEXPORT TECELLA_ERRNUM CALL tecella_auto_artifact_get | ( | TECELLA_HNDL | h,
|  | int | channel,
|  | double * | artifact,
|  | int | max_size,
|  | int * | actual_size |
| ) |  |  |

Gets the current artifact data for a given channel. The units for each sample in the artifact is Amps/Volts. If you scale each sample by the step size of a voltage pulse, you will get the artifact in Amps that will be removed from the response. Note: the artifact is always applied to the max sample rate available.

Parameters:

  | h | A handle to an initialized device.
  | channel | The channel you want the get the artifact removal of.
  | artifact | A pointer to an array of doubles where the API can store the values for artifact removal.
  | max_size | The maximum size of the artifact array.
  | actual_size | Returns the number of elements stored into artifact.

DLLEXPORT TECELLA_ERRNUM CALL tecella_auto_artifact_get_capacitance | ( | TECELLA_HNDL | h,
|  | int | channel,
|  | double * | capacitance |
| ) |  |  |

Returns the equivalent capacitance compensation of the artifact removal in Farads.

Parameters:

  | h | A handle to an initialized device.
  | channel | The channel you want the capacitance compensation of.
  | capacitance | The equivalent capacitance compensation of artifact removal for the given channel.

DLLEXPORT TECELLA_ERRNUM CALL tecella_auto_artifact_get_size | ( | TECELLA_HNDL | h,
|  | int | channel,
|  | int * | size |
| ) |  |  |

Gets the number of samples in the artifact for the given channel.

Parameters:

  | h | A handle to an initialized device.
  | channel | The channel you want the get the artifact removal size of.
  | size | Upon return, will contain the size of the artifact data.

DLLEXPORT TECELLA_ERRNUM CALL tecella_auto_artifact_set | ( | TECELLA_HNDL | h,
|  | int | channel,
|  | double * | artifact,
|  | int | size |
| ) |  |  |

Sets the artifact to be removed for a given channel. See tecella_auto_artifact_get() for a description of units used.

Parameters:

  | h | A handle to an initialized device.
  | channel | The channel you want set the artifact removal of.
  | artifact | A pointer to an array of doubles that the API will use as the new artifact.
  | size | The number of elements in artifact.

DLLEXPORT TECELLA_ERRNUM CALL tecella_auto_artifact_update | ( | TECELLA_HNDL | h,
|  | double | v_hold = `0`,
|  | double | t_hold = `19e-3`,
|  | double | v_step = `10e-3`,
|  | double | t_step = `19e-3`,
|  | int | iterations = `10`,
|  | int | unused_stimulus_index = `0` |
| ) |  |  |

Records artifacts that remain after capacitance compensation so that they can be removed automatically. This function automatically enables artifact removal, so you must call tecella_auto_artifact_enable() with enable=false if you don't want the artifact removal to be applied immediately after calling this function. Artifacts should be updated whenever there's a change in gain,compensations,or bessel filter. Note: tecella_auto_comp() automatically disables artifact removal.

Parameters:

  | h | A handle to an initialized device.
  | v_hold | The holding voltage used by the auto comp algorithm.
  | t_hold | Number of seconds to hold the holding voltage. Tip: Use a combined value for t_hold+t_step that does not resonate with any environmental noise, such as 50Hz or 60Hz noise.
  | v_step | The amplitude of the test pulse used by the auto compensation algorithm.
  | t_step | Number of seconds to hold the pulse. Also becomes the amount of time after an edge artifact removal will work in the future. Tip: Use a combined value for t_hold+t_step that does not resonate with any environmental noise, such as 50Hz or 60Hz noise.
  | iterations | How many vcmd pulses to average together when measuring the artifact. Fewer iterations are faster, but more iterations reduces noise.
  | unused_stimulus_index | An unused stimulus the algorithm can use for calibration. Only associated channels are calibrated.

DLLEXPORT TECELLA_ERRNUM CALL tecella_auto_comp | ( | TECELLA_HNDL | h,
|  | double | v_hold = `0`,
|  | double | t_hold = `20e-3`,
|  | double | v_step = `10e-3`,
|  | double | t_step = `20e-3`,
|  | bool | use_leak = `true`,
|  | bool | use_digital_leak = `false`,
|  | bool | use_cfast = `true`,
|  | bool | use_cslow_a = `true`,
|  | bool | use_cslow_b = `true`,
|  | bool | use_cslow_c = `true`,
|  | bool | use_cslow_d = `true`,
|  | bool | use_artifact = `true`,
|  | double | under_comp_coefficient = `0.0`,
|  | int | acq_iterations = `10`,
|  | int | unused_stimulus_index = `0` |
| ) |  |  |

Sets values for leak, cfast, and all the cslows that will compensate for parasitics in the response. All channels associated with the stimulus will be calibrated unless disabled using the function tecella_acquire_enable_channel(). If there's only 1 stimulus, this function cannot be used while acquiring. If there is more than 1 stimulus, this function may be used while acquiring in continuous mode as long as the unused_stimulus_index is not acquiring. If cfast or a cslow is used, artifact removal will automatically be disabled in order to get the best capacitance compensation. Note: tecella_auto_comp() automatically disables artifact removal.

Parameters:

  | h | A handle to an initialized device.
  | v_hold | The holding voltage used by the auto comp algorithm.
  | t_hold | Number of seconds to hold the holding voltage.
  | v_step | The amplitude of the test pulse used by the auto compensation algorithm.
  | t_step | Number of seconds to hold the pulse
  | use_leak | If true, algorithm will compensate for leak if supported by the hardware.
  | use_digital_leak | If true, auto comp digitally compensates for any leak not compensated by analog leak compensation. Use tecella_chan_get_digital_leak() to retreive the resulting compensation.
  | use_cfast | If true, algorithm will compensate using cfast if supported by the hardware. If false, cfast will remain untouched.
  | use_cslow_a | If true, algorithm will compensate using cslowa if supported by the hardware. If false, cslowa will remain untouched.
  | use_cslow_b | If true, algorithm will compensate using cslowb if supported by the hardware. If false, cslowb will remain untouched.
  | use_cslow_c | If true, algorithm will compensate using cslowc if supported by the hardware. If false, cslowc will remain untouched.
  | use_cslow_d | If true, algorithm will compensate using cslowd if supported by the hardware. If false, cslowd will remain untouched.
  | use_artifact | If true, artifact removal will automatically be updated. Not as accurate as running it separatly
  | under_comp_coefficient | Indicates the how much you prefer under-compensation to over-compensation. 0 indicates no preference. + indicates preference for under-compensation. - indicates preference for over-compensation. Magnitude indicates strengh of that preference. If positive, the max error over:under should be close to 1:(1+under_comp_coefficient). If negative, the max error under:over should be close to 1:(1-under_comp_coefficient).
  | acq_iterations | Indicates how many vcmd pulses to average before calculating compensations. Less iterations are faster, but more iterations are more accurate.
  | unused_stimulus_index | An unused stimulus the algorithm can use for calibration. Only associated channels are calibrated.

DLLEXPORT TECELLA_ERRNUM CALL tecella_auto_comp_offset_adjust_mode_get | ( | TECELLA_HNDL | h,
|  | int | channel,
|  | TECELLA_OFFSET_ADJUST_MODE * | mode |
| ) |  |  |

Gets the offset adjust mode to use when tecella_auto_comp is called

Parameters:

  | h | A handle to an initialized device.
  | channel | The channel. TECELLA_ALLCHAN is not allowed.
  | mode | A return pointer for mode of the given channel.

DLLEXPORT TECELLA_ERRNUM CALL tecella_auto_comp_offset_adjust_mode_set | ( | TECELLA_HNDL | h,
|  | int | channel,
|  | TECELLA_OFFSET_ADJUST_MODE | mode |
| ) |  |  |

Selects the offset adjust mode to use when tecella_auto_comp() is called. Note: the resulting offset adjust after tecella_auto_comp() is only valid for the gain at which tecella_auto_comp() was run. If you change the gain, you should turn off the offset adjust mode. You should enable an offset adjust mode if you suspect JP will drift between experiments and you cannot use a 0mV as required by tecella_auto_offset(). This will allow you to adjust the offset using the same stimulus as requested of tecella_auto_comp().

Parameters:

  | h | A handle to an initialized device.
  | channel | The channel. TECELLA_ALLCHAN is allowed.
  | mode | The offset mode to use for the given channel.

DLLEXPORT TECELLA_ERRNUM CALL tecella_auto_frequency_boost_filter | ( | TECELLA_HNDL | h,
|  | int | lpf_width,
|  | int | stimulus = `0` |
| ) |  |  |

Automatically applies a frequency boost filter for the current gain and bessel settings. Overwrites any filters set by tecella_sw_filter_set(). Not implemented yet...

Parameters:

  | h | A handle to an initialized device.
  | lpf_width | Short for low pass filter width. Allows you to apply a low pass/decimation filter in parallel with the frequency boost.
  | stimulus | A stimulus the function can use to acquire from.

DLLEXPORT TECELLA_ERRNUM CALL tecella_auto_offset | ( | TECELLA_HNDL | h,
|  | double | jp_delta = `0`,
|  | int | unused_stimulus_index = `0` |
| ) |  |  |

This function adds an offset to the stimulus to compensate for junction potentials or other battery effects EXTERNAL to the amplifier. This is accomplished by adjusting the JP register for each channel such that the measured current is as close to 0 Amps as possible for a 0 Volt stimulus. Make sure tecella_auto_calibrate() has already been run to remove any internal interference. All channels associated with the unused_stimulus_index will be compensated.

Note:
  This function sets to zero any offsets added to the response when offset adjust mode is set to RESPONSE.

Parameters:

  | h | A handle to an initialized device.
  | jp_delta | Auto offset uses jp=0mV and jp=(jp_delta)mV to determine the best jp per channel. 0 indicates don't care. This does not limit the final jp value, it only limits the jp values used to calculate the final jp value.
  | unused_stimulus_index | A stimulus index that is not currently playing. JP will be calculated for any channels associated with this stimulus.