Recent changes to MainTutorialDragonCurve

MainTutorialDragonCurve modified by Markus Ansmann

Markus Ansmann — Thu, 12 Feb 2015 00:21:16 -0000

--- v13
+++ v14
@@ -7,7 +7,7 @@

 Connecting to the LabRAD Manager
 --------------------------------
-Let's open LabVIEW and create a **New** **Blank VI**. In the Block Diagram, place a copy of the **Simple Client Connection.vi**, either from the **User Libraries** or the **Select a VI...** entry in you **Functions Palette** (depending on how you chose to install the components). Right-click on the **manager** input (top left) of the new VI and select **Create ``=>`` Control** from the pop-up menu. This should leave your Block Diagram looking something like this:
+Let's open LabVIEW and create a **New** **Blank VI**. In the Block Diagram, place a copy of the **Simple Client Connection.vi**, either from the **User Libraries** or the **Select a VI...** entry in your **Functions Palette** (depending on how you chose to install the components). Right-click on the **manager** input (top left) of the new VI and select **Create ``=>`` Control** from the pop-up menu. This should leave your Block Diagram looking something like this:
 [[img src=ManagerInfoBlockDiagram.png alt=screenshot]]

 It will also place the following control onto your VIs Front Panel:

MainTutorialDragonCurve modified by Markus Ansmann

Markus Ansmann — Sat, 31 Jan 2015 02:37:55 -0000

MainTutorialDragonCurve modified by Markus Ansmann

Markus Ansmann — Sat, 31 Jan 2015 02:34:34 -0000

--- v11
+++ v12
@@ -116,4 +116,6 @@

 ... to be continued ...

+ 
+
 ~ Markus Ansmann, Feb 27th, 2008

MainTutorialDragonCurve modified by Markus Ansmann

Markus Ansmann — Sat, 31 Jan 2015 02:32:48 -0000

--- v10
+++ v11
@@ -105,8 +105,11 @@
 [[img src=dtError.png alt=screenshot]]

 Even though it's probably clear what is going on, let's go over it quickly just for completeness:
+
 First, we send a Request to the Fractal Server's **Dragon** setting to ask it for the next 1000 points of the Dragon Curve. We try to convert the returned data into an Array of Clusters with two DBLs.
+
 If this succeedes, this array contains more data points. The little For Loop converts the data from __*(vv)__ (the type returned by the Fractal Server) to __*2v__ (the type required by the Data Vault) by applying the **Cluster To Array** function to each of the elements in the data array. The new data array is then passed to the Data Vault's **add** setting and the While Loop is continued.
+
 Once all the data has been returned by the Fractal Server, it will send an empty Reply to our Request. This cannot be converted into the array type we gave the Parse Packet VI and thus raises an error. In the **Error** case of the Case Structure, we clear this error and tell the While Loop to stop executing.

 Now, if you type in your password and select an iteration depth (try 10 for starters), the VI will create a new dataset and store all values in it. If you look at the Grapher, you should be able to watch the data come in and get plotted live.

MainTutorialDragonCurve modified by Markus Ansmann

Markus Ansmann — Sat, 31 Jan 2015 02:30:38 -0000

--- v9
+++ v10
@@ -91,17 +91,18 @@

 For our purposes here, let's use option 1, since we know that we are expecting a U32 back giving us the number of points in the curve.

-Since we only want to run the data-taking part of our code if the setup completed successfully, let's enclose it in a Case Structure. You may have already noticed the boolean **errors** output of the **Simple Request** VIs. This output returns [[image:True.png]] (True) if the Request failed entirely or if the Reply Packet contains any Error Records. We can use the two **errors** outputs of both of our requests and wire them together using an **Or** function into the **selector** input of the Case Structure. In the **True** case (the case where there was errors), we then simply forward the connection ID and errors through the Case Structure without any further processing. For now, this will leave our Block Diagram looking something like this:
-> [[image:initAll.png]]
+Since we only want to run the data-taking part of our code if the setup completed successfully, let's enclose it in a Case Structure. You may have already noticed the boolean **errors** output of the **Simple Request** VIs. This output returns [[img src=True.png]] (True) if the Request failed entirely or if the Reply Packet contains any Error Records. We can use the two **errors** outputs of both of our requests and wire them together using an **Or** function into the **selector** input of the Case Structure. In the **True** case (the case where there was errors), we then simply forward the connection ID and errors through the Case Structure without any further processing. For now, this will leave our Block Diagram looking something like this:
+[[img src=initAll.png alt=screenshot]]

 Now, we've pretty much covered all LabRAD specific functionality, so the rest of this part of the tutorial will be to use these skills to actually take some data.

-==Taking the Data==
+Taking the Data
+---------------
 Let's make the Case Structure a bit larger and add some more of the same things we already used above to its **False** case to make it look like this:
-> [[image:dataTaking.png]]
+[[img src=dataTaking.png alt=screenshot]]

 The **Error** case of the Case Structure inside the While Loop looks like this:
-> [[image:dtError.png]]
+[[img src=dtError.png alt=screenshot]]

 Even though it's probably clear what is going on, let's go over it quickly just for completeness:
 First, we send a Request to the Fractal Server's **Dragon** setting to ask it for the next 1000 points of the Dragon Curve. We try to convert the returned data into an Array of Clusters with two DBLs.

MainTutorialDragonCurve modified by Markus Ansmann

Markus Ansmann — Sat, 31 Jan 2015 02:28:13 -0000

MainTutorialDragonCurve modified by Markus Ansmann

Markus Ansmann — Sat, 31 Jan 2015 02:25:38 -0000

--- v7
+++ v8
@@ -73,17 +73,21 @@

 The reason why this is somewhat convoluted is two-fold: For one, the Parse Packet VI needs to accomodate the other two Parse Options explained below. But, more importantly, the version of LabVIEW that we use does not allow us to turn that group of three VIs (Parse Packet, Unbundle, and Variant To Data) into a single SubVI with the ability to accomodate any data input like the Variant To Data VI does.

-===Parse Option 2: Several Possible Reply Types===
+###Parse Option 2: Several Possible Reply Types###
 If there are a few known possibilities for what data type you are expecting as the answer you can use the following arrangement to extract the data and handle it according to its type:
-> [[image:parseTextContent.png]]
+[[img src=parseTextContent.png alt=screenshot]]
+
 Here, the Cluster wired to **accepted types** contains two prototype elements: A Number (U32) with the label **Number** and a String with the label **Text**. **Parse Packet** will now check for the FIRST element in your Cluster that matches the type (ignoring units!) of the data contained in the Record. It will return a Variant of that type at the **data** output and the **label** of the prototype element at the **type label** output.
+
 This label is used as the **selector** of a Case Structure. The Case Structure should handle the different possible cases (by label) independently.
+
 As shown here, you can wire your prototypes Cluster into the Case Structure and use **Unbundle By Name** to extract the correct prototype for the **Variant To Data** VI. The call to **Variant To Data** should ALWAYS succeed, provided the text shown inside **Unbundle By Name** matches the content of the **case selector label** and provided your labels inside the prototype Cluster are unique.

-===Parse Option 3: Unknown Reply Type===
+###Parse Option 3: Unknown Reply Type###
 If you have no idea what data type you might get returned (like when reading a parameter from a random dataset from the Data Vault), you can use the following arrangement:
-> [[image:parseVariant.png]]
-If you leave the **accepted types** input of the **Parse Packet** VI unwired, the VI will return the data converted into a Variant at its **data** output and the LabRAD Type Tag of the data at the **type label** output. If all you want to do is display the result to the user, you can create a Variant Indicator and wire it to **data**. It is NOT recommended that you use the **type label** output as the **selector** of a Case Structure since LabRAD Type Tags are not unique (they can contain random comments, whitespace, commas, etc.). You would instead need to write a function that actively parses the type tag.
+[[img src=parseVariant.png alt=screenshot]]
+
+If you leave the **accepted types** input of the **Parse Packet** VI unwired, the VI will return the data converted into a Variant at its **data** output and the LabRAD Type Tag of the data at the **type label** output. If all you want to do is display the result to the user, you can create a Variant Indicator and wire it to **data**. It is **not** recommended that you use the **type label** output as the **selector** of a Case Structure since LabRAD Type Tags are not unique (they can contain random comments, whitespace, commas, etc.). You would instead need to write a function that actively parses the type tag.

 For our purposes here, let's use option 1, since we know that we are expecting a U32 back giving us the number of points in the curve.

MainTutorialDragonCurve modified by Markus Ansmann

Markus Ansmann — Sat, 31 Jan 2015 02:21:47 -0000

--- v6
+++ v7
@@ -25,7 +25,7 @@
 After typing the correct password, though, an execution of the VI should complete without errors and update the **welcome message** and **client ID** indicators. You might also be able to see your LabVIEW client connection flash up in the LabRAD Manager for a brief second every time you execute it.

 **Aside:**
-*If you leave out **Simple Disconnect** and run your VI a couple of times, you might start to see connections piling up in the LabRAD Manager's list. I am not sure why LabVIEW sometimes closes the connections automatically and sometimes doesn't. That's why it's safer to always specifically ask for a disconnect. If you completely close LabVIEW, though, all the lingering connections should go away.*
+If you leave out **Simple Disconnect** and run your VI a couple of times, you might start to see connections piling up in the LabRAD Manager's list. I am not sure why LabVIEW sometimes closes the connections automatically and sometimes doesn't. That's why it's safer to always specifically ask for a disconnect. If you completely close LabVIEW, though, all the lingering connections should go away.

 Initializing the Dataset
 ------------------------
@@ -40,7 +40,7 @@
 [[img src=newCluster.png alt=screenshot]]

 **Aside:**
-*If you run a wire from this Cluster somewhere and hold the mouse over it, LabVIEW will show you its type in the **Context Help** (\[Ctrl\]+\[H\]) as:*
+If you run a wire from this Cluster somewhere and hold the mouse over it, LabVIEW will show you its type in the **Context Help** (\[Ctrl\]+\[H\]) as:
 [[img src=newClusterType.png alt=screenshot]]

 Finally, for **add parameter** (here: __sw__), we will build the data structure on the fly. For this, create a String constant containing **Iterations**. Drop a **Numeric Control** onto your Front Panel and change it's Label to **Iterations**. Double-click it to locate it in the Block Diagram. Right-click on it and change the **Representation** to **U32**. Again, you can uncheck **View As Icon** if you like. Use **Bundle** to combine the String constant and the Numeric Control into a Cluster:
@@ -60,13 +60,17 @@

 This request will return information - the number of points in the curve - that we will want to display to the user. We can extract it using the **Parse Packet** VI. There are three ways in which you can use this VI, depending on whether you know exactly what data type you are expecting in the Reply, or whether there is a couple of different possibilities, or whether you have absolutely no idea. Let's go over these:

-===Parse Option 1: One Possible Reply Type===
+###Parse Option 1: One Possible Reply Type###
 If you know exactly what data type you are expecting as the answer, or if you only care about one of the options, you can use the following arrangement to extract the data:
-> [[image:parsePointCount.png]]
+[[img src=parsePointCount.png alt=screenshot]]
+
 The left two VIs build and send the Request as before. The **records out** and the **error out** outputs of the **Simple Request** VI are wired into the **Parse Request** VI. The **index** output of the **Build Packet** VI is wired into the **index** input of **Parse Request**. The index is used to keep track of the potentially multiple Requests contained inside a Packet. The rest of the connections to this VI are needed to turn the returned data into a regular LabVIEW type.
+
 **Aside:**
-> LabVIEW is statically typed, i.e. it needs to know the type of each wire and input/output terminal as soon as you place it. But the **Build Packet** and **Parse Packet** VIs need to be able to handle data types that are unknown at that time. To allow for this flexibility, LabVIEW uses **Variants** (purple wires). A Variant is somehwat like a Cluster, except that LabVIEW doesn't require immediate knowledge of what is going to be inside it. This is made possible by severely restricting the capabilities of Variants. The most useful things you can do is turn them into binary strings and back (we use this to generate the data that actually goes out on the TCP connection) and to try to convert them into a specific regular data type. This latter conversion is achieved using the **Variant To Data** VI (the yellow one with the cog in the above diagram) from **Advanced ``=>`` Data Manipulation ``=>`` Variant** in your Functions Palette. This VI works by accepting a Variant input and a proto**type** for the data that you would like to extract from it. You can think of a prototype as an example piece of data whose sole purpose is to define the type of some other piece of data. The **Variant To Data** VI adjusts its output to match the wire going into the **type** input. This output can then be used like any other output of that data type.
+LabVIEW is statically typed, i.e. it needs to know the type of each wire and input/output terminal as soon as you place it. But the **Build Packet** and **Parse Packet** VIs need to be able to handle data types that are unknown at that time. To allow for this flexibility, LabVIEW uses **Variants** (purple wires). A Variant is somehwat like a Cluster, except that LabVIEW doesn't require immediate knowledge of what is going to be inside it. This is made possible by severely restricting the capabilities of Variants. The most useful things you can do is turn them into binary strings and back (we use this to generate the data that actually goes out on the TCP connection) and to try to convert them into a specific regular data type. This latter conversion is achieved using the **Variant To Data** VI (the yellow one with the cog in the above diagram) from **Advanced ``=>`` Data Manipulation ``=>`` Variant** in your Functions Palette. This VI works by accepting a Variant input and a proto**type** for the data that you would like to extract from it. You can think of a prototype as an example piece of data whose sole purpose is to define the type of some other piece of data. The **Variant To Data** VI adjusts its output to match the wire going into the **type** input. This output can then be used like any other output of that data type.
+
 The purpose of the **Parse Packet** VI is to turn the binary data in the received Records into a Variant using one of the types inside a Cluster that you wire into its **accepted types** input. If you are only expecting a single possible data type, the Cluster that you connect to **accepted types** only needs to contain one prototype element for that type (here: a U32 number). Using **Unbundle**, you can use this same prototype element as the **type** input of the **Variant to Data** VI. The output of this VI then contains the data from the Record. You can use the **error out** output of the whole chain to check if everything went ok.
+
 The reason why this is somewhat convoluted is two-fold: For one, the Parse Packet VI needs to accomodate the other two Parse Options explained below. But, more importantly, the version of LabVIEW that we use does not allow us to turn that group of three VIs (Parse Packet, Unbundle, and Variant To Data) into a single SubVI with the ability to accomodate any data input like the Variant To Data VI does.

 ===Parse Option 2: Several Possible Reply Types===

MainTutorialDragonCurve modified by Markus Ansmann

Markus Ansmann — Sat, 31 Jan 2015 02:12:44 -0000

--- v5
+++ v6
@@ -44,17 +44,18 @@
 [[img src=newClusterType.png alt=screenshot]]

 Finally, for **add parameter** (here: __sw__), we will build the data structure on the fly. For this, create a String constant containing **Iterations**. Drop a **Numeric Control** onto your Front Panel and change it's Label to **Iterations**. Double-click it to locate it in the Block Diagram. Right-click on it and change the **Representation** to **U32**. Again, you can uncheck **View As Icon** if you like. Use **Bundle** to combine the String constant and the Numeric Control into a Cluster:
-> [[image:addparameterCluster.png]]
+[[img src=addparameterCluster.png alt=screenshot]]

 Now, we need to add these three data structures as Records into a Request Packet. For this, we use three copies of the **Build Packet** VI. The VI is polymorphic and can accept either a number for its **setting** input or a string. This allows you to choose the Setting that the record is meant for either by ID or by Name. Place one of the three VIs next to each of your data structures and wire them into the **data** input. Add a String constant for each with the content **cd**, **new**, and **add parameter** respectively and wire them into the **setting** input. Finally, link the VIs' **records** inputs and **appended records** outputs in the order in which you would like the Records to be processed by the Server. This part of your Block Diagram should look something like this:
-> [[image:dvPacket.png]]
+[[img src=dvPacket.png alt=screenshot]]

 To send the Request out, we use the **Simple Request** VI. Stick a copy of it between **Simple Client Connection** and **Simple Disconnect** and wire the **appended records** output of the last **Build Packet** VI to its **records in** input. Make a String constant and set its content to **Data Vault** and wire it into the **target** input (this input is also polymorphic). Your entire Block Diagram should now look like this:
-> [[image:initDataset.png]]
+[[img src=initDataset.png alt=screenshot]]

 If you run your VI at this point, it will create empty datasets in the Data Vault with the correct axis labels and a parameter named **Iterations**.

-==Initializing the Data Run==
+Initializing the Data Run
+-------------------------
 Next, we need to initialize the data run by sending a Request to the Fractal Server's **Init Dragon** setting. To build this packet, all you need to do is place a **Build Packet** VI and wire its **setting** input to a String constant containing **Init Dragon** and its **data** input to the Numeric Control from before. To send it, use the **Simple Request** VI with its **target** input wired to a String constant containing **Fractals**. Stick this VI between the previous **Simple Request** and **Simple Disconnect** (See later for updated Block Diagram).

 This request will return information - the number of points in the curve - that we will want to display to the user. We can extract it using the **Parse Packet** VI. There are three ways in which you can use this VI, depending on whether you know exactly what data type you are expecting in the Reply, or whether there is a couple of different possibilities, or whether you have absolutely no idea. Let's go over these:

MainTutorialDragonCurve modified by Markus Ansmann

Markus Ansmann — Sat, 31 Jan 2015 02:09:11 -0000

--- v4
+++ v5
@@ -25,22 +25,23 @@
 After typing the correct password, though, an execution of the VI should complete without errors and update the **welcome message** and **client ID** indicators. You might also be able to see your LabVIEW client connection flash up in the LabRAD Manager for a brief second every time you execute it.

 **Aside:**
-> If you leave out **Simple Disconnect** and run your VI a couple of times, you might start to see connections piling up in the LabRAD Manager's list. I am not sure why LabVIEW sometimes closes the connections automatically and sometimes doesn't. That's why it's safer to always specifically ask for a disconnect. If you completely close LabVIEW, though, all the lingering connections should go away.
+*If you leave out **Simple Disconnect** and run your VI a couple of times, you might start to see connections piling up in the LabRAD Manager's list. I am not sure why LabVIEW sometimes closes the connections automatically and sometimes doesn't. That's why it's safer to always specifically ask for a disconnect. If you completely close LabVIEW, though, all the lingering connections should go away.*

-==Initializing the Dataset==
+Initializing the Dataset
+------------------------
 Since LabVIEW is the most restrictive of the languages we work with when it comes to data types, the LabRAD Data Types were chosen specifically to support LabVIEW. This makes it extremely straight forward to create LabRAD Packets in LabVIEW. All you need to do is create the data-structure you want to send and pass it directly into **Build Packet**.

 To create a new Dataset with the Data Vault, we need to first change into our working directory and then issue a **new** command and **add parameter**s. Let's build a packet that contains all three of these requests in one:

-For the **cd** Request's data (__*s__), drop an Array onto your Block Diagram and stick a single String constant into it. Resize the array container to show you 4 elements simultaneously. Double-click the first one and type **Test**. Type **Fractals** into the second one. Now, right-click the **Test** element and select **Data Operations ``=>`` Insert Element Before**. This will add another entry before **Test** that contains an empty string. Your resulting data structure is equivalent to the **['', 'Test', 'Fractals']** from before and should look like this:
-> [[image:cdArray.png]]
+For the **cd** Request's data (__*s__), drop an Array onto your Block Diagram and stick a single String constant into it. Resize the array container to show you 4 elements simultaneously. Double-click the first one and type **Test**. Type **Fractals** into the second one. Now, right-click the **Test** element and select **Data Operations ``=>`` Insert Element Before**. This will add another entry before **Test** that contains an empty string. Your resulting data structure is equivalent to the **\['', 'Test', 'Fractals'\]** from before and should look like this:
+[[img src=cdArray.png alt=screenshot]]

-For the **new** Request (__s*(ss)*(sss)__), create a Cluster containing a String, an Array of Clusters of two Strings, and an Array of Clusters of three Strings. Type **Dragon Curve** into the String of the main Cluster. Type **x** and **y** respectively into the first String of each of the first Clusters inside each of the Arrays. Leave the other entries empty. The data structure you get is equivalent to the **('Dragon Curve', [('x', '')], [('y', '', '')])** from before and should look like this:
-> [[image:newCluster.png]]
+For the **new** Request (__s*(ss)*(sss)__), create a Cluster containing a String, an Array of Clusters of two Strings, and an Array of Clusters of three Strings. Type **Dragon Curve** into the String of the main Cluster. Type **x** and **y** respectively into the first String of each of the first Clusters inside each of the Arrays. Leave the other entries empty. The data structure you get is equivalent to the **('Dragon Curve', \[('x', '')\], \[('y', '', '')\])** from before and should look like this:
+[[img src=newCluster.png alt=screenshot]]

 **Aside:**
-> If you run a wire from this Cluster somewhere and hold the mouse over it, LabVIEW will show you its type in the **Context Help** ([Ctrl]+[H]) as:
->> [[image:newClusterType.png]]
+*If you run a wire from this Cluster somewhere and hold the mouse over it, LabVIEW will show you its type in the **Context Help** (\[Ctrl\]+\[H\]) as:*
+[[img src=newClusterType.png alt=screenshot]]

 Finally, for **add parameter** (here: __sw__), we will build the data structure on the fly. For this, create a String constant containing **Iterations**. Drop a **Numeric Control** onto your Front Panel and change it's Label to **Iterations**. Double-click it to locate it in the Block Diagram. Right-click on it and change the **Representation** to **U32**. Again, you can uncheck **View As Icon** if you like. Use **Bundle** to combine the String constant and the Numeric Control into a Cluster:
 > [[image:addparameterCluster.png]]