Component Builder - User Interface

When you first execute the Component Builder you will be presented with a list of tabbed windows with the Component tab visible first. Please note that before you can define Inputs and Outputs you must first specify the Value Definitions and Spatial Definitions. Click on each tab to find out what each item is for.

Component Builder - Component Tab Default

The Component tab allows you to specify the following details for your component.

  • Caption - use this to name your component.
  • Description - use this to write a useful description of your component.
  • Id - this is a globally unique identifier generated by the Component Builder; there's no real need to change it at the moment.
  • Component Type - this indicates the type of the component. It defaults to ComponentStateTimeWithEngine and is read only.
  • Engine Type - click on this button to locate the dynamic link library or .NET assembly which contains your component engine. If the assembly or library contains more than one you will be able to select the appropriate engine.
  • Use Native Engine - check this box if the component engine you are wrapping is a native language library (eg FORTRAN or C++).

Now click on the Arguments tab and see how to specify Arguments for your component...

Component Builder Arguments Tab - empty

The Arguments tab allows you to specify arguments for your component. Click on Edit -> Row -> Add to add an argument to the list.  You will be presented with a list of available argument types from which you must select the most appropriate type for your argument.

Component Builder - Arguments type list

In our example we are defining a System.Double argument type. Select the type of argument you are defining and click the Save button Click the save button to close the window and save your selected argument type.  You will then be returned to the Arguments tab window. 

Component Builder - a double precision argument just added to the arguments list

The next step is to edit the argument we have just added to the list. Click on the item currently called "System.Double" (the little yellow warning triangle indicates you may wish to make some changes!).   You will then be presented with the argument editor window.

Component Builder - the argument editor window

Change the values of each fields according to your requirements - as a guideline:

  • Caption - change this to a sensible name for your argument
  • Description - add a sensible description of your argument
  • Id - again no need to change this GUID unless you have a specific reason to do so
  • ReadOnly - leave this as unchecked unless you really want your argument to be read only
  • Optional - check this box if the argument is optional - if it is you must ensure your component can cope without it
  • Default Value - do set this to a sensible value if your argument is Optional

Once you have set the values accordingly click the Save button Click the save button to close the window and save your changes  to be returned to the Argument list.  We've selected the following options as an example.

Component Builder - Argument attributes with values assigned

Now you know how to add arguments to your component in Component Builder click the Save button Click the save button save your arguments to a FCB file  to save your component build to a .FCB (FluidEarth Component Builder) file. You can then open this later from the File menu.

Bear in mind that before you define your Inputs and Outputs you will have to define the Value and Spatial Definitions for them so visit those tabs next...

Component Builder - Input tab

The Inputs tab allows you to specify inputs to your component. Click on Edit -> Row -> Add to add an input to the list.  You will be presented with a list of available input types from which you must select the most appropriate for your argument.

Component Builder - Inputs type list

Our example Pond component as defined its input exchange item (inFlow) as varying over space and time and hence we will select the first item in the list: InputSpaceTime to Engine. Select the appropriate type and click the Save button Click the save button.

Component Builder - Input Type selected

The next step is to configure the Input we have just defined so click on the first item (here indicated by the button labelled InputSpaceTime to Engine).

Component Builder - Input Type Inflow Edit

The next step is to specify sensible values for:

  • Caption - give the input a sensible caption (we're going to use inFlow)
  • Description - write a useful description of the input for those who come after
  • Engine Variable - this is the name of the variable which Pipistrelle uses to communicate with the engine - it is case sensitive
  • Value Definition - clicking here will allow you to select the Value Definition you created earlier
  • Spatial Definition - clicking here will allow you to select the Spatial Definition you created earlier

The values we selected for the properties for this Input are:

Component Builder - Input Type Inflow Edit Done

When you are happy with the values you have chosen click the Save button Click the save button.  You will return to the main Inputs tab and will see an Input item on the list (in our case called inFlow):

Component Builder - Inputs Done

The next step is to define the Outputs for our component - click on the Outputs tab.

Component Builder - Output tab

The Outputs tab allows you to specify outputs from your component. Click on Edit -> Row -> Add to add an output to the list.  You will be presented with a list of available output types from which you must select the most appropriate for your argument.

Component Builder - Outputs type list

Our example Pond component has defined its output exchange item (outFlow) as varying over space and time and hence we will select the first item in the list: OutputSpaceTime to Engine. Select the appropriate type and click the Save button Click the save button.

Component Builder - Output Type selected

The next step is to configure the Output we have just defined so click on the first item (here indicated by the button labelled OutputSpaceTime to Engine) and set the property values accordingly.

Component Builder - Output Type Outflow Edit

When you are happy with the values you have chosen click the Save button Click the save button.  You will return to the main Outputs tab and will see an Output item on the list (in our case called Outflow):

Component Builder - Outputs Done

The next step is to save the .FCB file and export the OMI and FCS files so we can use them in Pipistrelle.

Component Builder - Value Definition tab

Before one can specify Inputs or Outputs for a component, Pipistrelle needs to know what sort of value each item will be referring to. By specifying the value definitions in advance of setting the Inputs and Outputs you can build up a reusable list of types of Value Definitions including specifying how to convert them to and from SI units.

As before, you add an item to the Value Definitions list by selecting Edit -> Row -> Add from the main menu.

Component Builder - Value Definition Type

As you can see you can select one of three types of value definition. The first two, Quantity and Quality, will suffice for most purposes. The third, Value Definition, is for the more unusual customised requirements. For our purposes, Quantity is ideal - we're defining the amount of liquid flowing between Ponds. Once you have selected your type, click the Save button Click the save button save your arguments to a FCB file to return to the Value Definition window.

Component Builder - Value Definition - Quantity Selected

Then click on the Value Definition item itself (Quantity) to edit its attributes.

Component Builder - Value Definition - Quantity edit

As you can see there are a number of options available to you when definining a Quantity type value.

A sensible Caption and useful Description are essential, but as important is information about the Unit of the quantity in question and how to perform the Unit conversion to SI units. As our components use centilitres we will be specifying a Multiplication Factor of 100,000 to convert our centilitres to the SI unit of volume the cubic metre. In addition, we need to specify the Unit Dimension Powers (in our case we specify 3 for Length - three dimensions of space).

Component Builder - Value Definition - Quantity edit done

Once you have made suitable selections for your Quantity click the Save button Click the save button save your arguments to a FCB file to return to the Value Definition window.

Now we have defined the values we will be using the next step is to specify the Spatial Definitions of the data that the Inputs and Outputs will be using.  Go to the Spatial Definitions tab to find out more...

Component Builder - Spatial Definition tab

Before one can specify Inputs or Outputs for a component, Pipistrelle needs to know what sort of spatial data each item will be referring to. By specifying the spatial definitions in advance of setting the Inputs and Outputs you can build up a reusable list of types of spatial definitions.

As before, you add an item to the Spatial Definitions list by selecting Edit -> Row -> Add from the main menu.

Component Builder - Build

You need to have the Component tab open. 

Click on the Edit menu and select the Create OMI File... option. You will specify the filename for the .OMI file for Pipistrelle to use and Component Builder will also generate an .FCS file with the same file name and in the same directory. When Pipistrelle loads the OMI file it will search for the .FCS file specified in the .OMI file (this is specified by the Argument in the OMI file with the Key of FluidEarth2.Sdk.ComponentStateTimeWithEngine.Arg.Uri).

Once you have created the OMI file you can then use it in Pipistrelle as you would any other component.