Deployment

From Piki

Deployment is the act of extracting the system from within Synapse to a separate and stand alone .NET assembly (or .dll). This is done using the deployment postprocessor. This article is devoted to explain the structure and use of deployed component. Though .NET allows for other programing languages we will use C#. We will further assume you use the Visual Studio development environment from Microsoft for any coding exercises (although you can really use any text editor and access the C# compiler from the command line).

Quick start guide

In this section we will explain the minimum you will need to do to process your data via code. if you find it too brief, skip down to the beginners version.

In deployment you had the option to name your types. If you did not it will be called WorkArea0. This type is now found in the Peltarion.Deployed namespaces, so add a using directive.

using System;
using Peltarion.Deployed;
using Peltarion.Maths;

Peltarion.Maths is added to simplify the use of matrices.

Lets say you did not change the name of the type and that it is still called WorkAre0. To create an instance you can use the default constructor.

WorkArea0 net = new WorkAre0();

To feed the model with data you need to access the input formats. By default input formats are replaced by matrix input formats during deployment to simplify provision of data via code. The matrix input format has a few possibilities that take Matrix or double as argment. The different input formats of the model will be accessible via their names. If you had an input format named CSV you will find methods called Set_CSV and a Matrix property called Input_CSV.

Example one: double

net.Set_CSV(3.1415926, 2.71828183, 0, -1);

Example two: Matrix

Matrix m = new Matrix(3.1415926, 2.71828183, 0, -1);
net.Input_CSV = m;

To run the system:

net.StepEpoch();

To retrieve the output there will be a property that returns a Matrix and that is named after the last block prior to the |Delta Terminator (or according to what you specified during deployment).

If you forgot to name that last block and it is still called FunctionLayer4 or something of the like, you can access it with:

Matrix output = net.FunctionLayer4_Port0;

All together now, and encapsulated in a method (and using a third way to set the data):

private double[] MakeCalculation(double[] d)
{
    /* net should be instantiated somewhere else 
     * and passed in, or some such. Not to create 
     * it every time will gain you same speed. */
    WorkArea0 net = new WorkArea0();
    net.Set_CSV(d);
    net.StepEpoch();
    return net.FunctionLayer4_port0.data;
}

Not that hard really.

Quick start guide - beginners

In this section we will explain the minimum you will need to do to process your data via code. You will see that to use a deployed component is easy.

As an example of a deployed component we will use the police component created in tutorial 2.

Create a project

Create a project

First off we need a project to harbor our program. If you have one already, skip ahead.

Fire up VS. (Both 2005 or 2008 will work.) Use [File->New->Project...] or press [Ctrl+Shift+N]. For simplicity we will choose 'Console Application' and name it 'Quick'. Click OK.

Add a reference

Reference the assembly

Now we must add a reference to the deployed assembly. In the menu, find [Project->Add Reference...]. At the top of the pop-up window that appears you will find several tabs. Pick the one that reads 'Browse'. Find the location in which you have the deployed system. (default is My Documents\Peltarion Synapse\Deployed\) Select the assembly (or .dll) and click OK.

With the deployed police system from tutorial two, it would be: My Documents\Peltarion Synapse\Deployed\GoodCopBadCop\, and the assembly would be GoodCopBadCop.dll.

Add using directives

All types in .NET are sorted into different namespaces. The ones deployed from Synapse are in the Peltarion.Deployed namespace. At the top of the file Program.cs, that VS. just created for you, you will find a lot of rows starting with 'using'. Add these two lines to the code:

using Peltarion.Deployed;
using Peltarion.Maths;

This will tell the compiler to look in thees namespaces for types without us having to specifically state in what namespace to find the type every time we use it.

Why we want to add the Peltarion.Maths namespace is because it contains a matrix type that will be coming handy later. This can be a problem if you are creating a GUI application and have already included the System.Drawing.Drawing2D namespace as they both contain a type called Matrix. In that case you can either use Peltarion.Maths.Matrix every time you need it, or you can add a slightly different using directive that will let you access the Peltarion Matrix type as PMatrix instead of Matrix.

using PMatrix = Peltarion.Maths.Matrix;

Creating an instance of the model

When you deployed your system using the deployment postprocessor their was a text box at the top that read 'System Name'. The Type that contains the system after Deployment will have whatever name you put into that box. The default is WorkAre0 and in the police tutorial we named it GoodCopBadCop.

To create an instance of that Type use the default constructor. Go to the body of the Main method in the Program.cs code file and add:

TheNameOfYourType net = new TheNameOfYourType();

Using the police example the hole Program.cs file should now look like this:

using System;
using System.Collections.Generic;
using System.Text;
using Peltarion.Deployed;
using Peltarion.Maths;
 
namespace Quick
{
  class Program
  {
    static void Main(string[] args)
    {
      GoodCopBadCop net = new GoodCopBadCop();
    }
  }
}

Providing data

To feed the model with data we need to access the input formats. In Synapse we used input formats to load data. Often these input formats load data from a text file or from a database, but within a consuming application we often already have the data on a more accessible form. (The ideal being a double[].) This is why by default, the different input formats are replaced by matrix input formats, that are easy to use from code, during deployment. The different input formats of the model will be accessible via their names. If you had an input format named CSV you will find methods called Set_CSV and a Matrix set-property called Input_CSV.

Let's say you are using the police model and wish to run a police with the following values:

• note that the CSV input format expanded FinalE to FinalE_pass and FinalE_Fail, and even though the model does not use them or AvgE for prediction, we still need to supply values for them since the data unit that reads the data from the input format still expects to receive ten features.

If you just want to run one sample at the time the easiest is to use the Set_[InputFormatName](...) methods.

/* The last three zeros are just placeholders 
 * for AvgE, FinalE_Pass and FinalE_Fail */
net.Set_CSV(23, 4.2, 2, 0, 1, 0, 0, 0, 0);

If you want to run many samples at once you can put each sample as a row in a Matrix and use the set-property Input_[InputFormatName].

/*Assuming you have created a 
 *Peltarion.Maths.Matrix called policeData
 *where each row hold data about one police */
net.Input_CSV = policeData;

Running the model

To run the model and process the data you just supplied, use:

net.StepEpoch();

Retrieving the output

To retrieve the output there will be a get-property that returns a Matrix and that is named after the last block prior to the delta terminator (or according to what you specified during deployment). Actually their will be a property for each port that was specified as a Shortcut and they will be called [BlockName]_Port[portNumber] respectively. Most blocks only have one output port and further the last block in a network is often a function layer, so most of the time, if you have not named your output block, the get-property will be called FunctionLayer4_Port0 or FunctionLayer6_Port0 or something like that.

In the police tutorial we named the output function layer block to Output and hence we are now looking for a get-property called Output_Port0.

Matrix output = net.Output_Port0;

The police model had two output features, FinalE_Pass and FinalE_Fail (In that order). The output matrix will therefor have two columns. It will also have as many rows as there were input samples. As we used Set_CSV(...) we could only set one sample and so the matrix will have only one row. Let's extract the two output features from the matrix.

double good = output[0, 0]; // first row, first column
double bad = output[0, 1]; // first row, second column

Conclusion

Let's add a few Console.WriteLines and see what we have:

using System;
using System.Collections.Generic;
using System.Text;
using Peltarion.Deployed;
using Peltarion.Maths;
 
namespace Quick
{
  class Program
  {
    static void Main(string[] args)
    {
      GoodCopBadCop net = new GoodCopBadCop();
 
      Console.WriteLine("\n\nTest of Synapse deployed component.");
      Console.WriteLine("Runing police model with: 23, 4.2, 2, 0, 1, 0, 0, 0, 0, 0");
 
      /* The last three zeros are just placeholders 
       * for AvgE, FinalE_Pass and FinalE_Fail */
      net.Set_CSV(23, 4.2, 2, 0, 1, 0, 0, 0, 0, 0);
 
      net.StepEpoch();
 
      Matrix output = net.Output_Port0;
      double good = output[0, 0]; // first row, first column
      double bad = output[0, 1]; // first row, second column
 
      Console.WriteLine("Good:\t{0}", good);
      Console.WriteLine("Bad:\t{0}", bad);
      Console.WriteLine("\nPress any key to quit.");
      Console.ReadKey();
    }
  }
}

program output

Now press F5 within Visual Studio to compile and run the program. At the end of the output you should see something like:

Test of Synapse deployed component.
Runing police model with: 23, 4.2, 2, 0, 1, 0, 0, 0, 0, 0
Good:   0.00539214266256594
Bad:    0.994607812345734

Press any key to quit.

This is pretty much a Hello world for Synapse deployed components application. One can do rather much more with a deployed component but this shows the general idea of how to use one.

Structure

The Synapse model is striped of its higher logic (graphical interfaces and the like) and encapsulated in a .NET type of chosen name that resides in the Peltarion.Deployed namespace. The new, deployed Type is designed to be easy to use and though the main structure is always the same, component names are partially preserved. Some important parts of the model are also encapsulated and exposed to provide a simpler Interface. The whole thing is then packed into a single file .NET Assembly (a DLL) to be used outside Synapse in consumer applications.

The deployed component consists of the following parts:

• 1×Model Capsule Class (MCC)
• 1×Topology Class (TC)
• 1×Data Class (DC)
• N×Data Bag Class (DBC)

Model Capsule Class

Topology Class (TC)

Data Class (DC)

Data Bag Class (DBC)

Multiple deployed components

If one wish to use more than one deployed component we soon run in to a problem. Both components contain definitions for vital types used in both components. This in turn will upset the .NET CLR which will not be able to determine what type you wish to use.

To avoid this deploy your systems with the Single File Deployment check box un-checked. This will produce many .dll files instead of just one, but will also enable you to reference each assembly (.dll file) only ones although it is required by both systems.

Example

If we deploy two systems we should only reference each assembly (dll) once. The following table shows the output from two multi-file deployments with the first occurrence of each assembly in bold. The .XML files are part of the output and used by Microsoft Visual Studio IntelliSense but are not to be referenced.

Training deployed components

Deployed components can also be trained. By default the control system is deployed with the learning turned off. Learning can be reactivated using the NoUpdate property on the MCC.

Saving and restoring states

To save a system state use the ToXml() method and to restore it use the FromXml() method. The ToXml() method produces an instance of the basic .NET XmlDocument class.

System performance

If you have a supervised system that has one or more delta terminator blocks you can get the system performance programmatically. You do this by reading the MSE property from the delta terminator block. It represents the MSE (euclidian mean square error).

Assuming your delta terminator is called "Delta Terminator 1" and your system instance is called "sys":

double meanSquareError = sys.Topology.DeltaTerminator1.MSE;

Alternatively, you can in the deployment postprocessor define a shortcut to the delta terminator. In that case you will get a direct property under the system root that will allow you to get the output of the delta terminator. Even if you don't create the shortcut, you can access it through the Topology construct (although it will be in signal form rather than in matrix form). Note that the output will depend on the chosen error metric.

See also

• Deployment postprocessor