hardware_interfaces.pi_control module

class PiController(controller_name: str, stage_names: List[str], com_port: Optional[str] = None, pci_board_number: Optional[int] = None, name: str = 'PIControllerXY')

Bases: object

This function initializes the Physik Instrumente (PI) controller.

Warning

• Be sure that the controller and the stages are compatible, else you will get an error

• Be sure that all controller are connected and detected (!) by the computer

• Check in PIMikroMove) if necessary

The current controllers which are typically used

1. I-Lab:

   • C-413 (USB or COM-Port connection) with stages:

     • V-522.1AA - Interferometer Stage

   • C-843 (PCI board connection) with stages:

     • M-415.PD - IR Delay Stage

     • M-531.PD - UV/VIS Delay Stage

2. H-Lab:

   • C-413 (USB or COM-Port connection) with stages:

     • V-522.1AA - Interferometer Stage

   • C-843 (PCI board connection) with stages:

     • M-415.PD - IR Delay Stage

     • M-406.6PD - UV/Vis Delay Stage

Most information about the controllers and stages can be found in the respective data sheets or by opening PIMikroMove. PI also provides example files to understand the motor controll better.

Useful when implementing a new controller:

One useful command is “GCSCommands.funcs” which returns a list of available commands for the chosen stage. Upon switching a stage to a different controller, make sure all connections to controller are closed and turn off the power supply of the controller(s). Always check if the motor is supported by the respective controller which you want it to connect to. If it is necessary to connect a new controller via COM-port or TCPIP etc. please look into the documentation (mainly GSCDevice).

Do not forget to edit the classes properly (i.e. add If statements for different controllers).

Parameters

• controller_name (str) –

  The controller name which is defined by PI

  • E.g. “C-413”

• stage_names (List[str]) –

  Name of the stage/ motor for each axis which is defined by PI

  • E.g. stage_names = [“M-406.6PD”,”M-531.PD1”]

• com_port (str, optional) –

  Port to which the controller is connected to (if applicable). This number can be found when opening the program “PIMikroMove” and trying to connect the controller. Defaults to None.

  • E.g. “COM15”

• pci_board_number (int, optional) – Board number which specifies the slot inside the computer where the PCI-Card is located (if applicable). Defaults to None.

• name (str, optional) – Name / Identifier to give to this controller. This is relevant for log statements, especially when there is more than one Controller in the setup. Defaults to “PIControllerXY”.

controller_name

The controller name which is defined by PI

• E.g. “C-413”

Type

str

com_port

Port to which the controller is connected to (if applicable). This number can be found when opening the program “PIMikroMove” and trying to connect the controller.

• E.g. “COM15”

Type

str

stage_names

Name of the stage/ motor for each axis which is defined by PI

• E.g. stage_names = [“M-406.6PD”,”M-531.PD1”]

Type

List[str]

pci_board_number

Board number which specifies the slot inside the computer where the PCI-Card is located (if applicable).

Type

int

axes

List containing the number of axis for the corresponding stages.

Type

List[int]

axis_stage (dict of {int

str}): Dictionary with axes number as key and stage names as values.

reference_mode

Reference mode which is used for the stages. See inline comments for more details.

Type

List[str]

pidevice

GCSDevice object containing the functionalities of the PI Controller/ Device

Type

GCSDevice

id_controller

ID of the controller.

Type

str

reference_state

Returns (False) True if stage is (not) referenced.

Type

bool

servo_state

Returns (False) True if servo is turned (off) on.

Type

bool

auto_zero_state

Returns (False) True if stage is (not) auto-zeroed.

Type

bool

min_range

Minimum position the stage can move to.

Type

int

max_range

Maximum position the stage can move to.

Type

int

init_velocity

Initial velocity after initialization.

Type

float

init_position

Initial position after initialization.

Type

float

References

• The necessary documentation (Python API) for PI-Hardware can be found in the PI Python Libraries provided by PI.

• A filereferencing to the documentation can be found in the datasheets and installation folder which is privately provided.

• There also exists a file called “gsccommands.py”, “pitools.py” and “gcsdll.py” where every command is listed in great detail. It can be found in datasheets and installation folder which is privately provided.

check_if_stages_init()

Checks if stages/ axes are referenced. If applicable the function autozeroes the stages. Checks if servos are on.

The stages used to this point (‘V-522.1AA’ for ‘C-413’ and ‘M-531.PD1’ for ‘C-843’ ) auto-reference themselves upon pistartup command. However, AutoZero has to be performed seperately. It is important to check if the stage which you use is able to auto-zero. The function also checks if the servos are on.

end()

get_init_params()

Set velocity to a very low value (0.1) as default. Reads out all necessary initial parameters after initialization (max/ min position, current position etc.)

class PiStage(controller: hardware_interfaces.pi_control.PiController, axis: str, t_zero: float, direction: int, path_factor: int, velocity: float, name: str = 'XYZ Stage')

Bases: object

Provides all functionalities needed to communicate with the stage.

Initializes the necessary arguments for the control of the Pi stages. Converts millimeters to fs and vice versa for the purpose of setting the movement range etc. Possible to set velocity. Possible to calculate the frequency for waveform generation. Regular sweep movements and waveform movements are possible.

Parameters

• controller (PiController) – Object which results from initiating the PI controller. During this initialization, the controller and stage are initiated, referenced etc. For further commands (like move motor etc.) it is necessary to pass this object to PiStage since all gcs commands need it to work properly.

• axis (str) – Axis of the stage. E.g. controller “C-413” has axes “1” and “2” where motors can be connected.

• velocity (float) – Initial velocity of the stage in millimeter/second.

• t_zero (float) – Stage position where both pulses temporally overlapp on the detector. Unit in mm.

• direction (int) – Either -1 or +1. This is an important parameter to define in which direction the stage delay is defined. I.e. +1 would mean that to increase delays the stage needs to move to “more positive” positions (i.e. from 2.1 mm to 2.4 mm). If the stage is turned around by 180 degrees, now it would be necessary to set direction to -1 since it has to move to “more negative” directions (i.e. from 1.2 mm to 0.8 mm).

• path_factor (int) – Number of times the light pulse travels back and/or forth on the delay stage. This is relevant for the conversion of a femtosecond delay time into a corresponding distance in mm and vice versa. For standard delays stages with two mirrors this factor is 2. The two mirrors are used to reflect the pulse once back and once forth (1+1=2). Moving the stage a given distance will increase the beam path by double that amount. In the I-Lab the UV/VIS delay stage is setup such that beam is reflected twice back and forth (2+2=4). This is achieved by “re”reflecting the pulse back onto the stage at a different height. The appropriate path_factor for this stage is 4, because for a movement of a given distance on that stage the beam path changes by the quadruple the amount of this distance.

• name (str, optional) – Name / Identifier to give to this stage. This is relevant for log statements, especially when there is more than one stage in the setup. Defaults to “XYZ Stage”.

controller

Object which results from initiating the PI controller. During this initialization, the controller and stage are initiated, referenced etc. For further commands (like move motor etc.) it is necessary to pass this object to PiStage since all gcs commands need it to work properly.

Type

PiController

axis

Axis of the stage. E.g. controller “C-413” has axes “1” and “2” where motors can be connected.

Type

str

t_zero

Stage position where both pulses temporally overlapp on the detector. Unit in mm.

Type

float

name

Name / Identifier to give to this stage. This is relevant for log statements, especially when there is more than one stage in the setup. Defaults to “XYZ Stage”.

Type

str, optional

t_zero_in_fs

Stage position where both pulses temporally overlapp on the detector. Unit in fs.

Type

float

direction

Either -1 or +1. This is an important parameter to define in which direction the stage delay is defined. I.e. +1 would mean that to increase delays the stage needs to move to “more positive” positions (i.e. from 2.1 mm to 2.4 mm). If the stage is turned around by 180 degrees, now it would be necessary to set direction to -1 since it has to move to “more negative” directions (i.e. from 1.2 mm to 0.8 mm).

Type

int

path_factor

Number of times the light pulse travels back and/or forth on the delay stage. This is relevant for the conversion of a femtosecond delay time into a corresponding distance in mm and vice versa. For standard delays stages with two mirrors this factor is 2. The two mirrors are used to reflect the pulse once back and once forth (1+1=2). Moving the stage a given distance will increase the beam path by double that amount. In the I-Lab the UV/VIS delay stage is setup such that beam is reflected twice back and forth (2+2=4). This is achieved by “re”reflecting the pulse back onto the stage at a different height. The appropriate path_factor for this stage is 4, because for a movement of a given distance on that stage the beam path changes by the quadruple the amount of this distance.

Type

int

position

Absolute position of stage in mm.

Type

float

position_fs

Position of stage relative to t_zero in fs.

Type

float

velocity

Velocity of the stage in millimeter/second.

Type

float

velocity_fs

Velocity of the stage in femtoseconds/second.

Type

float

max_range_in_fs

Maximum movement position in femtoseconds.

Type

float

min_range_in_fs

Minimum movement position in femtoseconds.

Type

float

frequency

Frequency in Hz with which the stage will repeat the waveform. This is needed as feedback to properly choose the arguments for the waveform-generation.

Type

float

start_pos

Start position of the circular motion. Typically at the value of the offset. Unit in mm.

Type

float

wave_generator

Gives the wavegenerator an “identification” number i.e. 1.

Type

int

wave_table

The controller has 8 spaces for wave tables which can be stored. We use the 1.

Type

int

coherence_time

Maximum time between the fixed pulse and the movable pulse.

Type

float

amplitude

Amplitude of the coherence time scan / wavegeneration (+ buffer) in mm.

Type

float

reset_position

The reset position is the position at which the interferometer counter should be reset to 0 for the circular motion. Unit in mm.

Type

float

overshoot_factor

When using the wavegeneration functionality in combination with the interferometer counter it was observed that the actual amplitude (coherence time) decreases with an increase in frequency (velocity) of the wavegeneration and increases with an increase of the the speedupdown parameter. To counter this the overshoot_factor is used to increase the setup coherence time by its factor on both sides. Actual amplitude = coherence_time*(1+2*overshoot_factor) + buffer

Type

float, optional

overshoot_mm

Distance in mm that the stage overshoots beyond the specified coherence time on both sides. See setup_coherence_time_scan for further information.

Type

float

speedupdown

Only exists for stages with active wavegeneration. Sets how round the curve becomes at minimal/maximal amplitude. Necessary so that the motor does not make hard stops at these endpoints.

Type

float

approx_frequency

Clostest frequency that can be reached by wavegeneration to the requested frequency.

Type

float

__init__(controller: hardware_interfaces.pi_control.PiController, axis: str, t_zero: float, direction: int, path_factor: int, velocity: float, name: str = 'XYZ Stage')

Initializes the necessary arguments for the control of the Pi stages.

calculate_frequency(number_of_points: int, tablerate: int)

Calculates the frequency with which the stage will repeat the waveform. This is needed as feedback to properly choose the arguments for the waveform-generation.

Output duration = servo cycle time * output rate * number of points The “servo cycle time” (max: 200µs, min: 100 µs) is the time which the servo needs to go from one data point to the next. The “output rate” (also called tablerate) basically increases the servo cycle time per data point. Make sure that the resulting frequency is not a multiple of the laser frequency. We want to get a laser shot for every bin (size of bin = half of the wavelengths of a HeNe lasers) of the interferometer. Therefore it is important to have “no harmonic overlap” between the laser shots and the stagefrequency.

References

C-413 user manual provided by PI. Chapter 8.6 Wave Generator (p.151-176, especially p. 167)

Parameters

• number_of_points (int) – Number of points for period of the wave.

• tablerate (int) – Duration of a wave table point in multiples of servo cycle times (also see extended summary).

Returns

frequency of wavegeneration cycles in Hz

Return type

float

init_wavegen(number_of_points: int, amplitude: float, tablerate: int, offset: float, firstpoint: float, speedupdown: float, number_of_cycles: int = 1)

Configure a waveform (here: RAMP waveform) and make the stage move in trajectory of this waveform.

Warning

! Before calling the waveform function make sure to check ! wheather your function arguments return a reasonable frequency ! (see calculate_frequency function).

The RAMP waveform is defined by the arguments below. To experiment with possible waveforms and to see them in action it is advisable to open PI-Mikromove and use the waveform-generator. There it is also possible to obtain a preview of the waveform depending on the given parameters.

References

C-413 user manual provided by PI. Chapter 8.6 Wave Generator (p.151-176, especially p. 167).

gcscommands.py file.

Sample file wavegenerator_circle.py

Parameters

• number_of_points (int) – Number of points for one wave period. Differently: Length of the single scan line curve (PI documentation). Ranges from 0 to 4096.

• start_pos (float) – Start position of the circular motion in mm. For our purposes this would typically be the t_zero position (in mm). E.g. -10 as the lowest position of stage V-522.1AA.

• amplitude (float) – Amplitude of the circular motion mm. E.g. Amplitude = 20 with offset of -10 means that the upper (lower) bound of the motion is 10 (-10).

• number_of_cycles (int, optional) – Number of times in which the wavepattern is repeated. ! Set equal to 0 so that the motor repeats the wave ! indefinitely. Generator must be stopped ! “manually” with ! the stop_generator function then. Defaults to 1 (1 cycle).

• tablerate (int) – The table rate (also called “output rate”) increases the servo cycle time per data point. Duration of a wave table point in multiples of servo cycle times. See also function calculate_frequency.

• offset (float) – Offset in mm of the scan. This value offsets the wave on the amplitude axis. See “amplitude” argument for an example.

• firstpoint (float) – Index of the segment starting point in the wave table. Lowest possible value is 1. Typically the first datapoint in the wavetable is used.

• speedupdown (float) – Sets how round the curve becomes at minimal/maximal amplitude. Necessary so that the motor does not make hard stops at these endpoints.

move(position: float, wait: bool = True)

Moves specified stage to a predefined position (in fs) relative to t_zero position. If instructed, waits for movement to complete by halting the interpreter.

Parameters

• position (float) – Position in fs to which the stage should be moved.

• wait (bool, optional) – Determines wheather the program waits until stage is on target/ reached the given position. Defaults to True.

move_mm(position: float, wait: bool = True)

Moves specified stage to a predefined position (in mm). Waits between moving if instructed.

Parameters

• position (float) – Position in mm to which the stage should be moved.

• wait (bool, optional) – Determines wheather the program waits until stage is on target/ reached the given position. Defaults to True.

set_t_zero(t_zero: float)

Set a defined t_zero in mm.

The stage moves relative to the t_zero position with the move methods, or the wavegen method

Parameters

t_zero (float) – Stage position where both pulses temporally overlapp on the detector. Unit in mm.

set_velocity(velocity: float)

Sets velocity of the stage in femtoseconds/ second and optionally returns it.

Args: velocity (float): Value of the velocity [femtoseconds/

second] at which the stage should move. If stage velocity is exceeded the program returns an error.

set_velocity_mm(velocity: float)

Sets velocity of the stage and optionally returns it.

Parameters

velocity (float) – Value of the velocity [millimeters/ second] at which the stage should move. If stage velocity is exceeded the program returns an error.

setup_coherence_time_scan(coherence_time: float, frequency: float, speedupdown: int, buffer: float = 800, overshoot_factor: float = 0.1)

Calculates essential parameters for waveform generation such as number of points and tablerate from a given frequency. Also creates corresponding wavetable on controller.

Parameters

• coherence_time (float) – Maximum time in ps between the fixed pulse and the movable pulse.

• frequency (float) – Frequency in Hz with which the stage should move back and forth. Advisable to choose in such a way that it does not have periodicity with the laser frequency.

• speedupdown (int) – Sets how round the curve becomes at minimal/maximal amplitude. Necessary so that the motor does not make hard stops at these endpoints.

• buffer (float, optional) – “Negative coherence time” - Timerange in fs where fixed pulse comes before movable pulse. This is required to collect the interferogram as a whole (“both sides”). Defaults to 800 in fs.

• overshoot_factor (float, optional) – When using the wavegeneration functionality in combination with the interferometer counter it was observed that the actual amplitude (coherence time) decreases with an increase in frequency (velocity) of the wavegeneration and increases with an increase of the the speedupdown parameter. To counter this the overshoot_factor is used to increase the setup coherence time by its factor on both sides. Actual amplitude = coherence_time*(1+2*overshoot_factor) + buffer Defaults to 0.1.

start_wavegen()

Move to starting position (start_pos) and start wave generation movement.

stop_wavegen()

Stop the wave generation movement.

wait()

Wait for stage to reach target position.