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.
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.
<!-- ............................................................ --> <!-- 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
<!-- ............................................................ --> <!-- 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
For a more detailed discussion see Migration of Parameter files to the XML format