Kernel Components > Data input-output

Release Information

Project: Siconos
Internal Release Number: 1.0
Last update: November 29, 2006
Related Documents:
     
Data input-output component -> XML management


What for? Classes/objects for input-ouput of data. At the time: XML
Feature sets: F-2.002, and F-2.300 to F-2.306
Depencies: LibXml2, SiconosAlgebra (utils)
Sources directory name: Kernel/src/xml

The purpose of this component is to provide objects for data input-output management. At the time, the only available tool is XML.
It is then possible to load a partial or complete model from a user-defined xml-file or to save a model into a new xml file, to create a restart-file for future computation.

To find more details on objects described in this section, see Doxygen documentation of Siconos/Kernel.

General overview

The xml class architecture is the same as the model-modeling-simulation one:  to (almost) each class of these last three components corresponds an xml class (see  xml classes diagram at the bottom of the page).  All the data from xml input file are saved in a DOMtree. The data stored in the XML Management platform are only used for input and output but never used during the computations. That means the data from the DOM tree are read when the software is launched (if a XML input file is defined) and stored to the DOM tree a the end of a simulation or when user asks for it.

Main objects of this component are:

  • SiconosModelXML : highest level object of this component; a call to its constructor leads to the DOMtree building.

  • KernelObjectNameXML, KernelObject being any object of modeling or simulation component (examples: InteractionXML, SimulationXML ...) :  all those XML objects have access to the specific branch of the DOM tree (through xmlNode pointers) which contains the data relating to the corresponding object of the Kernel.
    For example, an InteractionXML is a kind of link or key between Interaction object and its required data provided in XML input file and saved in the DOMtree.

  • SiconosDOMTreeTools class provides a toolbox to manipulate the data of the platform and to store them under XML format. Its functionnalities are:
    • Load SiconosVector and SiconosMatrix functions from the xml DOM tree.
    • Save SiconosVector and SiconosMatrix functions to the xml DOM tree.
    • Getter and setter for boolean, integer, double and string values.
    • xmlNode creation functions for SiconocVector, SiconosMatrix, boolean, integer, double and string values.
    • Advanced DOM tree navigation functions.

XML Schema :


it is used to check validity of input data, according to rules specified in a xml-schema file (xml schema).
This schema describres what are the possible attributes for objects, if they are required or optional and so on.
To check each information, the schema regroups the defined attributes in several tags relating to Model, NSDS, DynamicalSystem, Interaction, Relation and NonSmoothLaw, Simulation, TimeDiscretisation, OneStepIntegrator, OneStepNSProblem.

XML input data file:

Examples of xml input file are available in examples (BouncingBall xml input file,...).
For more details on xml syntax see for example xml tutorial.

LibXML2 library (http://xmlsoft.org/)

The LibXML2 library is used in the platform to manage the xml files (data input/output). This is an XML C parser and toolkit, developed for the Gnome project (but not limited to the Gnome platform). It is a free software available under MIT License.

The main benefits of using LibXML2 are: 

  • its portability : LibXML2 is known to be very portable, the library should build and work without serious troubles on various systems (Linux, Unix, Windows, MacOS, MacOS X, RISC Os, ...) ;
  • LibXML2 passes all 1800+ tests from the oasis XML Tests Suite ;
  • its diversity : several APIs are implemented by LibXML2 like dom or sax ;

About the use and possibilities of LibXML2, it seems to be adapted and powerfull enought for our project : a prototype verifing, reading, and writing xml files has been developed, and the results are encouraging. However, the library has an important drawback : its poor documentation for modules, methods and structures.

Model loading from XML file

To built a new model from an XML input file, user has to call Model constructor with input file name as an argument.
Then SiconosModelXML constructor  is called and performs the following steps
  • parse XML input file.
  • check data validity, according to xml schema.
  • save data into the DOMtree and call constructors for SiconosModelXML members (SimulationXml and NonSmoothDynamicalSystemXML) and so on with children of these objects, till the lowest level is reached.
Then, after all the XML objects have been created, the siconos platform is  built: constructors for all children objects of the Model are called, with their corresponding XML object as argument:  NonSmoothDynamicalSystem( NonSmoothDynamicalSystemXML ),  Simulation ( SimulationXML) ... and so on with DynamicalSystem, Interaction etc.

Model saving in XML file

DOMtree saving occurs in two steps. First XML objects are updated and  the XML tree is compared with the Kernel tree, to create missing XML object (when new Kernel objects have been created during computation). Then Kernel data are copied in the DOM tree with all the XML objects. Finally  the DOM tree is saved into an XML file.
 Platform's data saving is leaded from the Model. The function which does this job is "saveToXMLFile",  with the following steps: 
  • checkXMLPlatform() :  verifications on XML Management platform. It checks the link between the platform's objects and the XML Management objects. If the XML Management platform does not exist,  it is created and linked to the objects of the siconos platform. Otherwise, every link between the platform and the XML Management is checked to ensure the availability of the XML platform objects.

  • savePlatformToXML() :  the information contained in the platform are saved in the DOM tree using the specific functions given by the XML object.

  • checkXMLDOMTree() : when data of the DOMtree are up to date, check they respect XML schema.

  • saveSiconosModelInXMLFile(xmlFile) :  write data in xmlfile.

XML classes diagram

  xml classes diagram