Simulation Files *.sub

Subsim simulation files provide to collect all simulation data in one file. You can specify the world with its passive (buoy, pipes...) and active objects (AUV) used for the simulation. Additionally default settings for view, physics and visualization can be given. A SubSim simulationfile has to have the suffix ".sub"

Writing a simulation file

File Structure

A simulation .sub file uses the xml syntax with all it features. This makes it easy to read and is nearly selfexplaining. See https://en.wikipedia.org/wiki/XML for more information about XML; Here an example file:

 <Simulation>
   <!-- note: docu example for a .sub file -->
   <Docu text="Author: Your Name"/>
   <World file="pool.xml" />
   
   <Docu>
    We have two WorldObjects
   </Docu>
   <WorldObjects>
     <Submarine file="./Mako/mako.xml" hdtfile="./Mako/mako.hdt"/>
       <Client file="./Mako/mako.dll"/>
     </Submarine>
     <WorldObject file="./buoy/buoy.xml">
       <Origin x="2.0" y="2.0" z="2.0">
     </WorldObject>
   </WorldObjects>
   
 <Simulation>

As you can see in the example, every simulation file has to start with the <simulation> tag and ends with the </simulation> end tag. End between different tags are allowed:

<World /> - specify the world

This tag specifys the a world settings file. For mor information see WORLD XML.
This tag is compulsory and can be used only once.

Give the filename with its path in the attribute "file". If no path given, the default path for world files is used.Example: 


      <Simulation>
       ...
       <world file="pool.xml"/>
       ...
      </Simulation>

<WorldObjects /> - List of all objects

This tag must surround all WorldObject tags. Wheter active or passive ones.

<WorldObject /> - specify passive object

This tag specifys the a passive WorldObject settings file. For mor information see WORLDOBJECT XML.
This tag is optional and can be used serveral time. It must be surrounded by "WorldObjects" tag

Give the filename with its path in the attribute "file". If no path given, the default path for worldobjects files is used.

To adjust position and orientation of the object, use the origin/orientation tag as in the following example: 


      <Simulation>
       ...
       <WorldObjects>
          <WorldObject file="./buoy/buoy.xml">
             <Origin x="82.0" y="-40.0" z="15" />
	     <Orientation roll="0.0" pitch="0.0" yaw="0.0" /> 
          </WorldObject>
       </WorldObjects>   
       ...
      </Simulation>

<Submarine> - specify a AUV as active object

This tag is an extension of the WordlObject tag and specifys the an active Submarine settings file. For mor information see WORLDOBJECT XML and PHYSICS XML.
This tag is optional and can be used once (by now). It must be surrounded by "WorldObjects" tag

Specify the path anf filename to the hdt file in the attribute "hdtfile".

To execute a controller program on this ative onject use the <Client> tag with attribute "file". Example: 


      <Simulation>
       ...
       <Submarine file="./mako/mako.xml" hdtfile="./HDT_files/mako.hdt">
          <Client file="./Mako/mako.dll"/>
          <Origin x="1.0" y="2.0" z="0.0"/>
       </Submarine>
       ...
      </Simulation>

<SimulatorSettings /> - overwrite default settings

This tag must surround all Simulation settings.

<Physics /> - overwrite default physics settings

<View /> - overwrite default view settings

<Visualize /> - overwrite default visualization settings

<Docu /> - documentation notes

The <Docu> tag gives a possibility to write some notes into the simulation file which will be displayed in the SubSim - message box. A simulation description, author name or anything else can be placed here. This tag is optional.

The text wether be in the text attribute or in the tag value. See usage in example above.

<!-- --> - Comments

Comments are meant for personal notes or to uncomment a part of the simulation file. They are completely ignored by SubSim.

All of the following lines will be ignored from subsim:


      <!-- note: docu example for a simfile -->
      <!-- <PluginParam PluginName="Client Manager" Run="./Example1.dll" \> -->
      <!-- commet over
      multiple lines -->

Writing a Sub-Simulation File

To run a programm you have to write a SimulationFile first. A Simulationfile specifies the environment of the simulation and its objects. SubSim simulationfiles have the ending *.sub.

The best way to understand how it works is to have a look in an example file:

	
    <Simulation>
     <World file="pool.xml" />
     <Submarine file="./Mako/mako.xml" hdtfile="./HDT_files/HDT_Mako.hdt">
		<Origin x="3.0" y="0.0" z="3.0"/>
	 </Submarine>
	 <WorldObject file="./buoy/buoy.xml" /> 
     <PluginParam PluginName="Client Manager" Run="./wallfollowing.dll"      /> 
    </Simulation>

The simulationfile is written in XML, so easy to read and nearly selfexplaining. The <World > tag specifies the environment where the AUV and the objects are moving in. Like a pool in this example. The Worldfiles can be found under /subsim/world/ and are also written in XML and very easy to understand (see the worldfile specifications).

The <Submarine> tag specifies the auv that we want to load with its hdt file. The hdt file is necessery for running eyebot controller simulations. See the section Eyebot hardware description table. The submarine XML-files a stored under /subsim/sub/ every object has its own directory.

<Origin> works in this way showed in the submarine tag in the same way for every WorldObject. With this tag you can specify the position of the object at subsim startup.

The <WorldObject> file is an object like a submarine, execpt it is passive and needs no hdt file. The XML description can also be found under /subsim/sub/

The <PluginParam> is the way you can controle the startub settings of every plugin used from subsim. Some plugins bring there own set of parameters with them, like the client manager. The client manager is responsible to load and run the program you've written for your auv. So we send the command "Run" with the value "./wallfollowing.dll" to the plugin "Client Manager". This causes that your programm is loaded and startet immediately when the simulation file was processed. If you don't like to subsim to start the programm immediately, change the line to:

	
   <PluginParam PluginName="Client Manager" LoadFile="./wallfollowing.dll"/>

and subsim will load the programm, but you have to start it manually by pressing the play button in the main GUI.