• The Janus C++ Library - An Interface Class for DAVE-ML ...

Sponsored Links

  •   
  • FileName: JanusRefMan_DSTO.pdf [preview-online]
    • Abstract: This XNS entry provides contact details for the author or his organisation ... This XNS entry provides contact details for the. author or his organisation in reference to this modiļ¬cation of the dataset. ...

Download the ebook

The Janus C++ Library - An Interface Class for
DAVE-ML Compliant XML-Based Flight Model Datasets.
Dr D. M. Newman
(on contract from Ball Solutions Group)
Air Vehicles Division
Defence Science and Technology Organisation
ABSTRACT
The Australian Defence Science and Technology Organisation's (DSTO) Flight Systems Branch
undertook a review of its aircraft flight model development processess in 2003. As an outcome
from the review it was decided to align future flight model dataset strucutres with the
American Institute of Aeronautics and Astronautics (AIAA) draft modelling and simulation
standard [AIAA, 2003] and the related Dynamic Aerospace Vehicle Exchange Markup
Language (DAVE-ML). Ball Solutions Group were contracted to develop an application
programming interface library to the DAVE-ML datset structure for use with flight dynamic
simulation and performance estimation models. The library is implemented in C++ and is
known as 'Janus'. The Janus library is detailed in this report.
RELEASE LIMITATION
Approved for public release
Published by
DSTO
506 Lorimer St
Fishermans Bend, Victoria 3207 Australia
Telephone: (03) 9626 7000
Fax: (03) 9626 7999
© Commonwealth of Australia 2005
August 2005
Copyright Agreement
This document is the property of the Australian Government. Permission is granted
to disseminate the Document as a reprint, translation, or as an entry in an abstracting
and indexing service, in soft and/ or hard copy. This agreement is subject to the
Commonwealth of Australia retaining Copyright and all other rights in the
Document in whatever form it appears, the author and source of the Document
being acknowledged, and no substantial changes being made in the Document
without the prior consent of the Releasing Authority, being Chief, Air Vehicles
Division, DSTO.
The author warrants that the Document is original work and does not infringe upon
any copyright, contains no libellous or otherwise unlawful statements and does not
otherwise infringe on the rights of others, and that any necessary permission to
quote from another source has been obtained.
APPROVED FOR PUBLIC RELEASE
DRAFT
b
THE JANUS C++ LIBRARY ­ AN INTERFACE
CLASS FOR DAVE-ML COMPLIANT
XML-BASED FLIGHT MODEL DATASETS
Document Number : 31495.002
Revision Number : Version 1.00
Document Date : 18 July 2005
DRAFT
DRAFT
JANUS LIBRARY FOR XML FLIGHT MODELS
AUTHORISATION
This document has been prepared by Ball Solutions Group, ABN 66 072 963 690 for the
Defence Science and Technology Organisation, Flight Systems Branch of Air Vehicles Division,
in accordance with Attachment A to Contracts No. 123394 and 139826.
D. M. Newman
Senior Aerospace and Flight Test Engineer
Ball Solutions Group
18 July 2005
Version: 1.00 of 18 Jul 2005
i
DRAFT
DRAFT
JANUS LIBRARY FOR XML FLIGHT MODELS
DOCUMENT REVISION HISTORY
Version Effect Date
0.90 Original Draft Release 23 July 2004
0.91 additional function documentation 15 October 2004
0.92 additional function documentation, including simple 14 December 2004
code examples
0.93 modified API to include 3 types of output variables, re- 22 December 04
placed dependent variable access procedures with out-
put variable access
0.94 multi-dimensional polynomial interpolation added 11 January 2005
0.95 ungridded interpolation added 7 February 2005
0.96 basic MathML logic capability added 11 February 2005
0.97 namespaces added 12 March 2005
0.98 file header processing and output 29 March 2005
0.99 string array handling added 30 June 2005
1.00 encrypted XML handling added 18 July 2005
Version: 1.00 of 18 Jul 2005
ii
DRAFT
DRAFT
JANUS LIBRARY FOR XML FLIGHT MODELS CONTENTS
Contents
Contents iii
List of Abbreviations v
1 Introduction 1
1.1 Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.2 Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.3 Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.4 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.5 Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2 Janus Module Documentation 4
2.1 Class Instantiation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.2 XML File Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.3 XML Tabulated Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.4 Output Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.5 Variables of All Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.6 Independent Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
2.7 MathML Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
2.8 XML File Encryption or Decryption . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
3 Janus Namespace Documentation 46
3.1 janus Namespace Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
3.2 januserr Namespace Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
4 Janus Class Documentation 47
4.1 Janus Class Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
4.2 JanusErr Class Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
5 Janus File Documentation 51
5.1 BreakpointDef.cpp File Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
5.2 Delaunay.cpp File Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
5.3 FileHeader.cpp File Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
5.4 Function.cpp File Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
5.5 GetDescriptors.cpp File Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Version: 1.00 of 18 Jul 2005
iii
DRAFT
DRAFT
JANUS LIBRARY FOR XML FLIGHT MODELS CONTENTS
5.6 GetValues.cpp File Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
5.7 GriddedTableDef.cpp File Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
5.8 Janus.cpp File Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
5.9 Janus.h File Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
5.10 JanusErr.cpp File Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
5.11 JanusErr.h File Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
5.12 JanusSecurity.h File Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
5.13 LinearInterpolation.cpp File Reference . . . . . . . . . . . . . . . . . . . . . . . . . 59
5.14 Ludcmp.cpp File Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
5.15 PolyInterpolation.cpp File Reference . . . . . . . . . . . . . . . . . . . . . . . . . . 60
5.16 Security.cpp File Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
5.17 SetMath.cpp File Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
5.18 SetValues.cpp File Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
5.19 Svd.cpp File Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
5.20 UngriddedInterpolation.cpp File Reference . . . . . . . . . . . . . . . . . . . . . . . 62
5.21 UngriddedTableDef.cpp File Reference . . . . . . . . . . . . . . . . . . . . . . . . . 63
5.22 VariableDef.cpp File Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
References 65
Version: 1.00 of 18 Jul 2005
iv
DRAFT
DRAFT
JANUS LIBRARY FOR XML FLIGHT MODELS LIST OF ABBREVIATIONS
List of Abbreviations
ADF Australian Defence Force
AIAA American Institute of Aeronautics and Astronautics
AVD Air Vehicles Division
DAVE-ML Dynamic Aerospace Vehicle Exchange Markup Language
DoF degree of freedom
DOM Document Object Model
DSTO Defence Science and Technology Organisation
DTD Document Type Description
FS Flight Systems Branch
MathML Mathematical Markup Language
NaN Not-a-Number
SI Systeme International d'Unites
XML eXtensible Markup Language
Version: 1.00 of 18 Jul 2005
v
DRAFT
DRAFT
JANUS LIBRARY FOR XML FLIGHT MODELS INTRODUCTION
1 Introduction
1.1 Background
Defence Science and Technology Organisation (DSTO) Flight Systems Branch has reviewed
its flight model development and maintenance processes, in conjunction with the require-
ments of Defence flight model users [Newman, 2004], and has decided to align its future
flight model dataset structures with the American Institute of Aeronautics and Astronau-
tics (AIAA) draft modelling and simulation standard [AIAA, 2003] and the related Dynamic
Aerospace Vehicle Exchange Markup Language (DAVE-ML) Document Type Description (DTD)
[Jackson & Hildreth, 2002], [AIAA, 2004]. Ball Solutions Group has been contracted to de-
velop a programming library, providing an application programming interface to the DAVE-ML
dataset structure, for use by DSTO Flight Systems in future development of performance,
flight dynamic and other aircraft models. The library is implemented as a C++ class known
as `Janus.'
1.2 Purpose
This document outlines the usage and structure of the Janus C/C++ programming library
which is under development for DSTO Flight Systems Branch by Ball Solutions Group.
1.3 Scope
The elements of the Janus library described in this document are:
a. Methods of instancing the Janus class,
b. The related JanusErr class, which provides information related to library initialisation
problems,
c. Public types in the classes,
d. Public functions in the classes, and
e. Source file components applicable to each function.
1.4 Overview
The library provides a flight modelling programmer with direct access to an eXtensible
Markup Language (XML) dataset which conforms to the draft AIAA modelling standard as
implemented under the DAVE-ML DTD version 1.7b1 [AIAA, 2004], in the form of a C++ class.
It was developed under Linux using the gcc 3.3.4 compiler, and has received limited testing
under Microsoft Windows 2000 using the Visual C++ compiler and under Microsoft Windows
XP using the cygwin environment and the gcc 3.3.1 compiler. To load and parse an XML file,
the Janus class makes use of the Apache Xerces-C++ validating XML parser library, currently
at version 2.5.0.
When initialised, which requires the calling program to supply an XML dataset file name, the
library creates and loads a Document Object Model (DOM) from the file, using the Xerces-C++
parser, then extracts numerical data from the DOM and stores it in a arrays for access from
the calling program through the Janus interface. Depending on the dataset and the applica-
tion, further initialisation may be required after first instantiation. During the initialisation
Version: 1.00 of 18 Jul 2005
1
DRAFT
DRAFT
JANUS LIBRARY FOR XML FLIGHT MODELS INTRODUCTION
process, problems with the XML file or its contents will cause a JanusErr to be thrown, pro-
viding a relevant message. If the calling program does not catch this error, execution will
abort.
With initialisation complete, the calling program can supply the current state values of rele-
vant independent variables through the Janus interface and receive in return a single output
variable value compatible with the independent variables. The forms of the data and the
interpolation, curve fitting or function evaluation required to generate the dependent vari-
able value are controlled by the XML data file content and are transparent to both the calling
program and the user. For these functions, which may be called repeatedly during program
execution, speed of execution is a priority and so limited error checking or notification is
performed.
Errors from the post-initialisation functions of the Janus instance therefore have the potential
to cause aborts without the option of handling by the calling program. However, the returned
values may be used to determine error conditions, since errors in functions returning double
precision data always return Not-a-Number (NaN), errors in functions returning string data
always return a zero pointer, errors in functions returning integer data or flags always return
-1, and errors in functions returning enums return an ERROR[*] value.
At any stage after initialisation, the Janus instance may be queried for details of any variable
or function, including units, names, descriptions, minima, maxima, and interpolation or
extrapolation attributes.
1.5 Data Types
To the modeller whose code uses a Janus instance to determine variable values, the under-
lying form of the XML dataset is irrelevant. However, the dataset developer needs to take
account not just of the DAVE-ML DTD which guides production of a well-formed, valid dataset,
but also of how the Janus treats each data type. The three main data types which will be
encountered are:
a. Gridded data, arranged in up to 32 dimensions on a regular grid, which can be interpo-
lated or extrapolated either linearly or using polynomials of order zero (nearest) to three
inclusive;
b. Ungridded data, a cloud of arbitrarily located data points forming a convex hull, which
is partitioned using Delaunay triangulation and interpolated multi-linearly; and
c. Functional representation in Mathematical Markup Language (MathML) form, which is
evaluated in accordance with the mathematical operators shown in the dataset. At
present Janus implements only the more common operators and qualifiers defined in
the MathML DTD. It deals only with real number data, but includes logical operators
which return Boolean qualifiers within a calculation element.
For every dataset to be accessed, there will be a preferred data type based on the form of
the data and its possible applications. In choosing how to represent a particular piece of
data within the XML dataset, the modeller should consider how to best make use of Janus's
capabilities. Where relevant to computational comparisons below, the software is considered
as running on a `typical' engineering-use PC circa 2005, under either Windows + Cygwin or
Linux. Some aspects which may be relevant are:
a. Gridded data using linear interpolation is generally the fastest to evaluate, with Janus
performing several million evaluations per second on a representative aerodynamic
dataset. As the number of degrees of freedom is increased for datasets of equivalent
complexity, function evaluation speed typically halves for each additional degree of free-
dom.
Version: 1.00 of 18 Jul 2005
2
DRAFT
DRAFT
JANUS LIBRARY FOR XML FLIGHT MODELS INTRODUCTION
b. Polynomial interpolation of gridded data is typically several times slower than linear
interpolation of the same data.
c. Ungridded data is generally the slowest to evaluate. For one degree of freedom (DoF)
data, an ungridded interpolation will typically take four or five times as long as grid-
ded interpolation of the same data based on the same breakpoints. This is because
of the added complexity of the barycentric coordinate computation used to weight the
contributing data points. In addition, as the number of degrees of freedom is increased
for datasets of equivalent complexity, function evaluation speed typically reduces by an
order of magnitude for each additional degree of freedom.
d. Extrapolation of any form of data is inherently risky. If you choose to take the risk,
gridded data extrapolation is much safer than ungridded data extrapolation. Because
the ungridded data is processed in barycentric coordinates, not cartesian coordinates,
and checking cartesian directions wastes processing time, Janus will only extrapolate
such data if all independent variables of the function are set to be extrapolated in both
directions.
e. MathML functions are evaluated at speeds similar to gridded data of equivalent complex-
ity. However, high order polynomial evaluation can be computationally costly. Luckily,
high order polynomials are almost always a bad choice for representation of aeronautical
data.
f. An extension to the DAVE-ML standard allows arrays of strings to be stored in and
accessed from gridded tables. The applications of this are quite limited, and the related
function documentation should be fully complied with for successful use.
Version: 1.00 of 18 Jul 2005
3
DRAFT
DRAFT
JANUS LIBRARY FOR XML FLIGHT MODELS INSTANTIATION
2 Janus Module Documentation
2.1 Class Instantiation
Enumerations
· enum Janus::VersionType { Janus::SHORT, Janus::LONG }
Functions
· char Janus::getJanusVersion (const VersionType versionType)
· char Janus::getXmlFileName ()
· Janus::Janus (const char documentName, const bool validate)
· Janus::Janus (const char documentName)
· Janus::Janus ()
· int Janus::setDomValidation (const bool validate)
· int Janus::setXmlFileName (const char documentName)
· int Janus::writeXmlFile (const char fileName)
· Janus::Janus ()
2.1.1 Detailed Description
The initialisation functions relate to the construction and destruction of a Janus instance.
They perform XML initialisation and instance an Xerces parser, then load from the supplied
XML file to a DOM structure and create numeric arrays based on the XML data.
The early stages of the initialisation process will throw JanusErr exceptions if the XML file is
not found or does not load or parse successfully. If the calling program does not catch these
exceptions, the program will abort. An example of exception handling, applicable to all forms
of Janus initialisation, is:
int iflag;
try {
iflag = prop.setXmlFileName( fileName );
}
catch ( const JanusErr &excep ) {
cerr


Use: 0.4331