The XML file format of the Parameter files

This page explains the current status of the simulation parameter files in Simthetic, its relation to class parameters and constructor arguments. Not all of simthetic is already implemented in this way; see Migration of Parameter files to the XML format for an explanation of those parts that still use a different approach for the parameter file.

Parameterfiles

Every class that is used in Simthetic and its libraries usually has several parameters that are different in different simulation setups (e.g.: the number of output bits in the simthlib::BitGenerator class; the number of reflection paths in the simthlib::WssusChannel radio channel). These parameters should therefore be read from a configuration file at simulation startup time (the file is called "the parameter file"), and the values should somehow passed on to the respective objects.

The parameterfiles are written in an XML file format. The actual format is described in a Document Type Definition (DTD) in xml/parameterfile.dtd, copied below. Of course these files can be created or edited by hand, but the graphical tool ksimthetic will also read and write these files, which is probably more convenient.

Current and recommended implementation

The parameters of a device that can be configured for each simulation are stored as so-called properties in a simth::PropertyList. Each of the properties in that list has a name, a type and a value. The lookup of values in a device is performed with template function Device::getProperty<T>() which will also check for the correct type of this property.

For a concrete simulation there is a powerful mechanism in place which will read all properties from the parameterfile xml file so that each device can access its properties at runtime. The programmer of a device does not need to care about how this happens; the programmer can simply call Device::getProperty<T>() to retrieve the simulation parameters.

Nevertheless, a programmer does have to define the properties that actually exist for a particular device. To do this, the definition of a Device's PropertyList resides in an additional XML file which is called the devicelist file. The file format is specified with a DTD which can be found in xml/devicelist.dtd, copied below. These additional XML file(s) are installed together with the actual library in a directory which is specified at installation time of simthetic. These devicelist files should also contain as much documentation of all properties as possible, because the documentation from there is also used by doxygen when creation the HTML documentation that you are reading right now.

DTD for parameterfile

The DTD for the XML-based parameter file is the following:

<!-- ............................................................ -->
<!-- 
Typical Invocation:
#  <!DOCTYPE parameterfile PUBLIC 
#   "-//TUHH//Simthetic Parameterfile V1.0//EN" 
#   "parameterfile.dtd">

Purpose:

  Proposed DTD for specifying the parameters of one concrete
  simulation run of the simthetic simulation system. This file is
  meant for the final solution where every Device of Simthetic is
  solely configured via a PropertyList. In this final case, this
  parameter file would simply "fill in the values" for all properties
  of the used devices.
-->
<!-- ............................................................ -->


<!ELEMENT parameterfile (simulationparameters*)>
<!ATTLIST parameterfile
   xmlns:gui CDATA #FIXED "http://simthetic.sourceforge.net/dtd/gui/1.0">
<!-- Note: The URL for the namespace does not have to point to any
     valid location. It is simply used to distinguish from possible 
     other namespaces. -->

<!ELEMENT simulationparameters (title?, devicevalues?, variables?,
                       devicesvalues, loopvariables, connectionlist,
                       gui:objects?) >
<!-- title = (unimplemented) Short descriptive title of this simulation
     devicevalues = This holds the global properties of the simulation 
                    system. The name is (admittantly) misleading, but this
                    is by far the easiest implementation, hence we stick 
                    with this element here.
     variables = A list of string variables (name and value) that 
                 can be re-used in the values of other properties 
                 by writing $(variable_name).
     devicesvalues = The list of devices and their properties 
     loopvariables = The list of loop variables and their settings
     connectionlist = The list of connections between the devices
     gui:objects = List of additional GUI objects (text, lines) which 
                   might be useful for explaining the system.
-->

<!ELEMENT title (#PCDATA)>
<!ELEMENT description (#PCDATA)>

<!ELEMENT variables (variabledef*)>
<!ELEMENT variabledef (description?, value)>
<!ATTLIST variabledef 
   name ID #REQUIRED>

<!ELEMENT value (#PCDATA)>

<!ELEMENT propertyvalues (propertyvalue*)>
<!ELEMENT propertyvalue (value)>
<!ATTLIST propertyvalue
   name CDATA #REQUIRED>

<!ELEMENT devicesvalues (devicevalues*)>
<!ELEMENT devicevalues (description | propertyvalues | gui:point)*>
<!ATTLIST devicevalues
   id ID #REQUIRED
   type CDATA #REQUIRED
   gui:rotation CDATA #IMPLIED>

<!ELEMENT loopvariables (loopvariable*)>
<!ELEMENT loopvariable (description?, value+)>
<!ATTLIST loopvariable
   id ID #REQUIRED
   name CDATA #REQUIRED
   type CDATA #REQUIRED>

<!ELEMENT connectionlist (connection*)>
<!ELEMENT connection (description?, gui:point*)>
<!ATTLIST connection 
   fromid IDREF #REQUIRED
   fromintf CDATA #REQUIRED
   toid IDREF #REQUIRED
   tointf CDATA #REQUIRED
   active (true|false) "true">

<!ELEMENT gui:point EMPTY>
<!ATTLIST gui:point    
   x CDATA #REQUIRED
   y CDATA #REQUIRED>

<!ELEMENT gui:objects (gui:text | gui:polygon)*>
<!ELEMENT gui:text (gui:point, value)>
<!ATTLIST gui:text
   gui:rotation CDATA #IMPLIED>
<!ELEMENT gui:polygon (gui:point*)>

The syntax of a DTD is described e.g. here: http://xmlsoft.org/xmldtd.html

DTD for parameterfile

The DTD for the devicelist XML files is as follows:

<!-- ............................................................ -->
<!-- 
Typical Invocation:
#  <!DOCTYPE devicelist PUBLIC 
#   "-//TUHH//Simthetic Devicelist V1.0//EN" 
#   "devicelist.dtd">

Purpose:

  This DTD was developed to specify the properties of a Device in the
  simulations system Simthetic. Basically, an XML file adhering to
  this XML should specify everything about a device that is needed by
  any GUI.
-->
<!-- ............................................................ -->

<!-- A devicelist file can include many device definitions. The
     include element (see explanation there) can appear file-wide here, or
     can appear in particular devices. -->
<!ELEMENT devicelist (include*, device*) >

<!-- Each device element describes one C++ class. The C++ typename has
     to appear in the type attribute. The libraryname attribute contains
     the name of the shared library this device is implemented in. The
     extends attribute contains the name of the C++ base class, if this
     device is derived from another one. The abstract attribute is true if
     the C++ class is an abstract class.  -->
<!ELEMENT device (include*, description, inputinterfaces?, 
                  outputinterfaces?, overriddenproperties?, propertylist?) >
<!ATTLIST device
   name CDATA #REQUIRED
   type ID #REQUIRED
   libraryname CDATA #REQUIRED
   extends CDATA #IMPLIED
   abstract (true|false) "false">

<!-- The include element should point to the file name that contains
     the devicelist of the base class. This is just for helping the
     DeviceManager finding all necessary xml files. -->
<!ELEMENT include (#PCDATA)>
<!ELEMENT description (#PCDATA)>

<!-- The input- and outputinterfaces describe all the interfaces of a
     device. The attribute "multiplied_by" contains the name of a
     property, which, if it is set, gives the number of multiple
     instances of this interface that will actually exist.
-->
<!ELEMENT inputinterfaces (interface*)>
<!ELEMENT outputinterfaces (interface*)>
<!ELEMENT interface (description?)>
<!ATTLIST interface 
   type CDATA #REQUIRED
   multiplied_by CDATA #IMPLIED>

<!-- Sometimes, a derived class will override properties of the base
     class by its own values as defined in the C++ code. The names of these
     properties are listed in this element. -->
<!ELEMENT overriddenproperties (value*)>

<!-- Most important for the definition of a useful simulation
     scenario: The propertylist describes all properties that are available
     in this device. The propertylist defined here is also directly used
     inside simthetic when the objects are created. -->
<!ELEMENT propertylist (property*)>

<!ELEMENT property (default?, description, option*)>
<!ATTLIST property
   name CDATA #REQUIRED
   type (bool | int | unsigned | double | complex | string | 
         list_string | enum | sequencelength | vector_octal_int |
         vector_double | octal_int ) #REQUIRED
   empty_default (true|false) "false"
   obsolete (true|false) "false"
   grouping CDATA #IMPLIED>

<!-- For most property types, the option element describes possible
     values that particularly make sense for this property (please add
     appropriate descriptions). But for properties of type 'enum' the
     semantics are different: For 'enum' properties, the property is only
     allowed to have values that are mentioned here as option elements. -->
<!ELEMENT option (value, description?)>

<!-- The default element simply contains a default value for a
     property. If it is empty and the property attribute empty_default is
     false, then this property has to be set in the simulation parameter
     file. -->
<!ELEMENT default (#PCDATA)>
<!ELEMENT value (#PCDATA)>

The syntax of a DTD is described e.g. here: http://xmlsoft.org/xmldtd.html

Current Status

Unfortunately some of the classes in Simtheticlib (approx. 50 out of the ~150) are still in old-approach implementation. These cannot currently be used from any XML parameterfile. If you encounter a C++ class that is not accessible from the XML parameterfile and does not show up in ksimthetic, you probably found such a case.

For a more detailed discussion see Migration of Parameter files to the XML format

---