calix.common.base.Calib

class calix.common.base.Calib(parameter_range: calix.common.base.ParameterRange, n_instances: int, inverted: bool = False, errors: Optional[List[str]] = None)

Bases: abc.ABC

Base class for calibration applications.

Accepts parameter range and other generally important settings. From here, Calibrations can be derived, implementing functions for at least measuring results and configuring parameters. Only one-dimensional calibrations are supported, i.e. only one variable is adjusted to move towards a desired target value.

Variables

  • parameter_range – Allowed range for parameter.

  • inverted – Invert calibration, i.e. expect a higher parameter returning a lower result. Defaults to False.

  • n_instances – Number of objects (e.g. neurons) to calibrate.

  • errors – Error messages to be logged when instances of the calibration have reached the parameter_range boundaries. If None, nothing will be logged. The first (second) error message is used when the lower (upper) bound is reached. Error messages are expected to support the .format() operation. As parameter {0}, the indices of failed instances are inserted, as parameter {1}, the respective boundary value is inserted.

  • target – Target read for calibration. Can be found during prelude, otherwise needs to be supplied to the run() method.

  • result – List: Calibrated parameters and success mask. Only available after run() has been called.

Raises

ValueError – if parameter_range has a bad shape or is too small.

__init__(parameter_range: calix.common.base.ParameterRange, n_instances: int, inverted: bool = False, errors: Optional[List[str]] = None)

Initialize self. See help(type(self)) for accurate signature.

Methods

__init__(parameter_range, n_instances[, …])

Initialize self.

configure_parameters(builder, parameters)

Function to set up parameters for testing.

measure_results(connection, builder)

Function to measure the observable.

postlude(connection)

Function to do necessary postconfiguring of the chip.

prelude(connection)

Function to do necessary pre-configuration or other things that are required during the actual calibration, like finding the target values.

run(connection, algorithm[, target])

Use the provided algorithm to find optimal parameters.
abstract configure_parameters(builder: calix.common.base.WriteRecordingPlaybackProgramBuilder, parameters: numpy.ndarray) → calix.common.base.WriteRecordingPlaybackProgramBuilder

Function to set up parameters for testing.

Use the provided builder to append instructions that configure the provided parameters. Then return the builder again. If one needs to wait between configuring the parameters and measuring, e.g. after setting a new CapMem value, this should be done here.

Parameters

  • builder – Program Builder to which configuration instructions can be appended.

  • parameters – Array of parameters that should be set up. Only integer parameters will be used.

Returns

The Program Builder with instructions to set up the given parameters appended.

abstract measure_results(connection: pyhxcomm_vx.ConnectionHandle, builder: calix.common.base.WriteRecordingPlaybackProgramBuilder) → numpy.ndarray

Function to measure the observable.

Typically this will read the CADC channels and return an array of the obtained reads. Use the provided builder to append read instructions, run it using the provided connection. If necessary, treat the results in any way, e.g. calculate statistics per quadrant if calibrating global settings. Then return an array that fits the number of parameters to update.

Parameters

  • connection – Connection where builder can be executed in order to measure results.

  • builder – Builder where instructions to read something can be appended.

Returns

An array with the measurement results in a shape that corresponds to the calibration instances. Any type that allows comparison to a calibration target using an operator < is allowed, in particular int and float.

postlude(connection: pyhxcomm_vx.ConnectionHandle) → None

Function to do necessary postconfiguring of the chip. If not overwritten, this function does nothing.

Parameters

connection – Connection to the chip to be calibrated.

prelude(connection: pyhxcomm_vx.ConnectionHandle) → None

Function to do necessary pre-configuration or other things that are required during the actual calibration, like finding the target values. If not overwritten, this function does nothing.

Parameters

connection – Connection to the chip to be calibrated.

run(connection: pyhxcomm_vx.ConnectionHandle, algorithm: calix.common.base.Algorithm, target: Optional[Union[numbers.Integral, numpy.ndarray]] = None) → calix.common.base.ParameterCalibResult

Use the provided algorithm to find optimal parameters.

Calls prelude function, calls algorithm.run(), calls postlude function. If self.target is not defined after the prelude function, the calibration target is required as a parameter to this function.

Parameters

  • connection – Connection to the chip to calibrate.

  • algorithm – Instance of an algorithm to be used for calibration. Will be hooked to the calibration during running and unhooked afterwards.

  • target – Target result to be aimed for. If given, this target is used. If None, the attribute self.target is used.

Raises

TypeError – If neither the target parameter or the attribute self.target are defined.

Returns

ParameterCalibResult, containing the optimal parameters.