Data input-output component -> XML
management
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.
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