dklfgj dfgjmpsdklg dfgjdsklfg dfjglksdfjg sdfgjokdfjg dfgjoksdfjg sdfgjksdlfgjsdf gdgjopksdfgj

Configuring APSIM User Interface for a new model

The APSIM User Interface needs to be told about any new model.

For the purposes of this guide, we'll assume that the Gross Margin model is being added the the User Interface.

Edit

Creating a Plugin XML file¶

The first step to telling the User Interface about GrossMargin is to create an XML plugin file that contains all the meta-data about the new model. This XML file contains pointers to icon files, documentation and a mechanism on how to create a .sim file to pass to APSIM.

<Type name="GrossMargin">
  <MetaData>
    <UItype>VBUserInterface.GenericUI</UItype>
    <ShowInMainTree>Yes</ShowInMainTree>
    <Image>%apsim%\UserInterface\Images\banner2.jpg</Image>
    <Documentation>GrossMargin.htm</Documentation>
    <LargeIcon>%apsim%\UserInterface\Images\GrossMargin32.png</LargeIcon>
    <SmallIcon>%apsim%\UserInterface\Images\GrossMargin16.png</SmallIcon>
    <DLL>%apsim%/Model/GrossMargin.%dllext%</DLL>
    <drops>
      <drop>toolbox</drop>
      <drop>simulation</drop>
      <drop>folder</drop>
    </drops>
    <ApsimToSim>
      <component name="[GrossMargin.name]" executable="[dll]">
        <executable name="[dll]" version="1.0" />
        <initdata>
      	[Model]
        [GrossMargin.innerxml]
        </initdata>
      </component>
    </ApsimToSim>
  </MetaData>
  <Model>
     <GrossMargin/>
  </Model>
</Type>

This plugin file points to many auxiliary files (png, html, jpg etc). It also tells the user interface which "UI" to use on the right hand side on the user interface. In this example, the GrossMargin component will use:

VBUserInterface.GenericUI

This particular UI is used by many models in APSIM. It simply interprets the XML chunk it finds in the .apsim file. To recap, the Gross Margin model has these parameters:

   <Param()> Private NCost As Double = 0
   <Param()> Private NApplicationCost As Double = 0
   <Param()> Private WaterCost As Double = 0
   <Param()> Private Price As Double = 0
   <Param()> Private MinimumProtein As Double = 0
   <Param()> Private ProteinIncrement As Double = 0

This means the XML chunk in the .apsim file will look like this:

  <GrossMargin>
    <NCost>1.2</NCost>
    <NApplicationCost>15</NApplicationCost>
    <WaterCost>0</WaterCost>
    <Price>140</Price>
    <MinimumProtein>10.5</MinimumProtein>
    <ProteinIncrement>2</ProteinIncrement>
  </GrossMargin>

The GenericUI will display this XML like this:
This can be improved by adding metadata to the XML chunk in the .apsim file:

  <GrossMargin>
    <NCost type="text" description="Nitrogen cost ($)">1.2</NCost>
    <NApplicationCost type="text" description="Nitrogen application Cost ($/ha)">15</NApplicationCost>
    <WaterCost type="text" description="Water cost ($)">0</WaterCost>
    <Price type="text" description="Price ($)">140</Price>
    <MinimumProtein type="text" description="Minimum protein (%)">10.5</MinimumProtein>
    <ProteinIncrement type="text" description="Protein increment (%)">2</ProteinIncrement>
  </GrossMargin>

Now the GenericUI will look like this:

Edit

Telling the User Interface about the Plugin XML file¶

The next step is to let the User Interface know about this plugin XML file. This is best done by clicking "Options" in the User Interface, select the PlugIns tab and then click the "Add" link at the bottom of the window. You can then navigate to the plugin xml file.

Edit

Creating a toolbox¶

The next step is to create a toolbox so that the user can drag an XML chunk and drop it on their simulation. A toolbox is just another XML file and looks like this:

<folder name="GrossMargin toolbox">
   <GrossMargin>
    <NCost type="text" description="Nitrogen cost ($)">1.2</NCost>
    <NApplicationCost type="text" description="Nitrogen application Cost ($/ha)">15</NApplicationCost>
    <WaterCost type="text" description="Water cost ($)">0</WaterCost>
    <Price type="text" description="Price ($)">140</Price>
    <MinimumProtein type="text" description="Minimum protein (%)">10.5</MinimumProtein>
    <ProteinIncrement type="text" description="Protein increment (%)">2</ProteinIncrement>
  </GrossMargin>
</folder>

This toolbox XML file can then be given to the User Interface by clicking Options in the User Intface and then the "Add a toolbox" link at the bottom of the Options window.

Edit

Letting the User Interface discover the new model's variables and events¶

To fully integrate the new model into the User Interface involves running UpdateDotNetProxies.exe from the %apsim%\Model directory. The User Interface will then probe the new model's DLL (and all other APSIM DLL's) and discover all of it's variables and events and make them available to the user in the outputfile variables and reporting frequency lists.