#ABSTRACT: Lab::Measurement for DUMMIES - Example 2 - Nested Sweeps
#PODNAME: Lab::Measurement::Examples::Example2_Gate_IV_scan

__END__

=pod

=encoding UTF-8

=head1 NAME

Lab::Measurement::Examples::Example2_Gate_IV_scan - Lab::Measurement for DUMMIES - Example 2 - Nested Sweeps

=head1 VERSION

version 3.823

=head1 Abstract

This is a simple, but fully functional Lab::Measurment script. Its purpose as a
measurement script is to record a set of IV-curves at a series of gate
voltages. However it is also a tutorial, that introduces the nested sweep
feature. Beginners should read Example1 first.

=head1 Introduction 

Example 1 presented a step by step tutorial in writing a simple
Lab::Measurement script using the Moose sweep functionality. In this example we
show how to extend this script, in order to get a set of IV-curves at a series
of gate voltages. Lab::Measurement offers nice features to implement this
extension in a very simple and mostly already familiar way. In the following,
we will focus the new parts of our script and discuss their meaning.

 #-------- 0. Import Lab::Moose -------------
 
 use Lab::Moose;
 
 #-------- 1. Initialize Instruments --------
 
 my $sample = "cnt13a";

 my $bias = instrument(
    type => 'YokogawaGS200',
    connection_type => 'LinuxGPIB',
    connection_options => {pad => 3},
    max_units_per_step => 1,
    max_units_per_second => 20,
    min_units => -10,
    max_units => 10,
 );

 my $biasdivider = 1000;
 # the bias voltage is divided 1:1000 in hardware

 my $multimeter = instrument(
    type => 'Keysight34470A',
    connection_type => 'VXI11',
    connection_options => {host => '192.168.3.28'},
    nlpc => 10;
 );
 
 my $gate = instrument(
    type => 'YokogawaGS200',
    connection_type => 'LinuxGPIB',
    connection_options => {pad => 1},
    max_units_per_step => 0.01,
    max_units_per_second => 0.1,
    min_units => -10,
    max_units => 10,
 );

 my $sensitivity = 1e9;
 # the preamplifier converts 1nA -> 1V
 
 #-------- 2. Define the Sweeps -------------

 my $gate_sweep = sweep(
    type       => 'Step::Voltage',
    instrument => $gate,
    from => -5,
    to => 5,
    step => 0.002
 );
 
 my $bias_sweep = sweep(
    type       => 'Step::Voltage',
    instrument => $bias,
    delay_in_loop => 0.05,
    delay_before_loop => 10,        # wait 10s before sweep
    from => -5,                     # reminder: voltage divider 1:1000
    to => 5,
    step => 0.005
 );

 #-------- 3. Create a a datafile and plot ---

 my $datafile = sweep_datafile(
    columns => [qw/gate bias current/]
 );

 $datafile->add_plot(
    type => 'pm3d',
    x => 'gate',
    y => 'bias',
    z => 'current'
 );

 #-------- 4. Measurement Instructions -------
 
 my $meas = sub {
    my $sweep = shift;
    my $gate = $gateyoko->cached_level();
    my $current = $multimeter->get_value() / $sensitivity;
    my $bias = $biasyoko->cached_level() / $divider;
    $sweep->log(
        gate    => $gate,
        bias    => $bias,
        current => $current,
    );
 };

 #-------- 5. And run it ... ----------------
 
 $gate_sweep->start(
    slave       => $bias_sweep,
    measurement => $meas,
    datafile    => $datafile,
    folder      => $sample.'diamonds',
    date_prefix => 1,
 );

 1;

=head1 The code

=head2 Instrument initialization

 #-------- 0. Import Lab::Moose -------------

 use Lab::Moose;

 #-------- 1. Initialize Instruments --------

 my $sample = "cnt13a";

 my $bias = instrument(
    type => 'YokogawaGS200',
    connection_type => 'LinuxGPIB',
    connection_options => {pad => 3},
    max_units_per_step => 1,
    max_units_per_second => 20,
    min_units => -10,
    max_units => 10,
 );

 my $biasdivider = 1000;
 # the bias voltage is divided 1:1000 in hardware

 my $multimeter = instrument(
    type => 'Keysight34470A',
    connection_type => 'VXI11',
    connection_options => {host => '192.168.3.28'},
    nlpc => 10;
 );

 my $gate = instrument(
    type => 'YokogawaGS200',
    connection_type => 'LinuxGPIB',
    connection_options => {pad => 1},
    max_units_per_step => 0.01,
    max_units_per_second => 0.1,
    min_units => -10,
    max_units => 10,
 );

 my $sensitivity = 1e9;
 # the preamplifier converts 1nA -> 1V

In this first part of this script, we are doing more or less the same as in
Example 1. We import the Lab::Moose module, and theninitialize the instruments
that we need. What's new is that we initialize here a third instrument,
the bias voltage source, which is again a Yokogawa GS200. No big deal, so far.

In addition, we define a few constants that characterize our experiment: the
sample name $sample, the factor of a voltage divider that is placed between
bias Yokogawa and sample $biasdivider, and the sensitivity of a current
preamplifier $sensitivity.

=head2 Sweep Objects

 #-------- 2. Define the Sweeps -------------

 my $gate_sweep = sweep(
    type       => 'Step::Voltage',
    instrument => $gate,
    from => -5,
    to => 5,
    step => 0.002
 );

 my $bias_sweep = sweep(
    type       => 'Step::Voltage',
    instrument => $bias,
    delay_in_loop => 0.05,
    delay_before_loop => 2,         # wait 2s before sweep
    from => -5,                     # reminder: voltage divider 1:1000
    to => 5,
    step => 0.005
 );

In this experiment, we want to measure the current through our sample, depending
on two parameters: the bias (or source-drain) voltage and the gate voltage.
Of course, that means we need instead of only one sweep now two sweeps. And as
you see, we create a second sweep which we call $gate_sweep.

We intend that the "outer loop" is the gate sweep. For each gate voltage value,
the bias sweep is executed. Since we want to make sure the preamplifier has
settled after returning the bias voltage to the start value, we add to the bias
sweep a parameter delay_before_loop of 2 seconds.

=head2 The datafile and the plot

 #-------- 3. Create a a datafile and plot ---

 my $datafile = sweep_datafile(
    columns => [qw/gate bias current/]
 );

 $datafile->add_plot(
    type => 'pm3d',
    x => 'gate',
    y => 'bias',
    z => 'current'
 );

There is almost nothing new here, except that the plot type is now pm3d. This
creates a color coded 2D plot. Therefore we have to specify a third axis, the
z-axis, which defines the values, which will be presented color-coded
in the plot later on.

=head2 4. The measurement instructions

#-------- 4. Measurement Instructions -------

 my $meas = sub {
    my $sweep = shift;
    my $gate = $gateyoko->cached_level();
    my $current = $multimeter->get_value() / $sensitivity;
    my $bias = $biasyoko->cached_level() / $divider;
    $sweep->log(
        gate    => $gate,
        bias    => $bias,
        current => $current,
    );
 };

Again, almost nothing new here. Note how we use the various variables that we
defined above.

=head2 5. Running it.

This is the place where now we have to put the two sweeps together.

 #-------- 5. And run it ... ----------------

 $gate_sweep->start(
    slave       => $bias_sweep,
    measurement => $meas,
    datafile    => $datafile,
    folder      => $sample.'diamonds',
    date_prefix => 1,
 );

We start the gate sweep (the outer loop), and at the same time tell it to run
the bias sweep as "slave", i.e., as inner loop.

And that's it!

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2022 by the Lab::Measurement team; in detail:

  Copyright 2017       Simon Reinhardt
            2018       Andreas K. Huettel


This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut
