FoX documentation.

All in one page

Separate pages

Introduction

API documentation

COMMON interface

OUTPUT interfaces

These documents describe all publically usable APIs.

If a subroutine or function, or indeed one of its arguments, is not mentioned above, it is not to be considered part of the stable API, even if it is accessible.

The astute developer is reminded that all times the final reference documentation is the source, which is publically available.

Other things


FoX versioning

This documentation describes version 2.0 of the FoX library

FoX was originally based on the version 1.2 of the xmlf90 library, but has since evolved heavily.

This release version includes only output modules.

(which is a further development of the xmlf90 library, last released as version 1.2)

This is a stable branch, which will be maintained with important bugfixes, but on which no further major development will occur.

Version 2.0 has support for outputting complete XML documents, with support for all XML objects described in XML11, and XML Names. FIXME. A detailed description of its precise conformance level is at [FIXME] link.

In addition, there is a large suite of routines available for outputting valid CML documents.

Input modules are under development for SAX, DOM, and XPath, and will be released with version 2.1.


Configuration and compilation

You will have received the FoX source code as a tar.gz file.

Unpack it as normal, and change directory into the top-level directory, FoX.

Requirements for use

FoX requires a Fortran 95 compiler - not just Fortran 90. All currently available versions of Fortran compilers claim to support F95. If your favoured compiler is not listed as working below, I recommend the use of g95, which is free to download and use.

The following compilers are tested and are known to work:

The following compilers are tested and known to fail

Other compilers are untested; reports of their success or failure are welcomed.

Configuration

This should suffice for most installations. However:

  1. If you have more than one Fortran compiler available, or it is not on your PATH, you can force the choice by doing:

    config/configure FC=/path/to/compiler/of/choice

  2. It is possible that the configuration fails. In this case

    • please tell me about it so I can fix it
    • all relevant compiler details are placed in the file arch.make; you may be able to edit that file to allow compilation. Again, if so, please let me know what you need to do.
  3. By default the resultant files are installed under the objs directory. If you wish them to be installed elsewhere, you may do

    config/configure --prefix=/path/to/installation

Note that the configure process encodes the current directory location in several places. If you move the FoX directory later on, you will need to re-run configure.

Compilation

In order to compile the full library, now simply do:

make

This will build all the FoX modules, and all the examples. However, you may only be interested in building the libraries, or perhaps a subset of the libraries. In that case, the following targets are available:

wxml_lib
wcml_lib

Testing

Two test-suites are supplied; one in common/test and one in wxml/test. In both cases, cd to the relevant directory and then run ./run_tests.sh.

The tests will run and then print out the number of passes and fails. Details of failing tests may be found in the file failed.out.

Known failures:
* test_xml_Close_2 sometimes unexpectedly fails - this is not a problem, ignore it. * On Lahey, 16 tests in wxml/test will fail - this is a flaw in the testsuite, the library is actually working correctly. Please ignore this problem.

If any other failures occur, please send a message to the mailing list (FoX@lists.uszla.me.uk) with details of compiler, hardware platform, and the nature of the failure.

Linking to an existing program

A script is provided which will provide the appropriate compiler and linker flags for you; this will be created after configuration, in the top-level directory, and is called FoX-config. It may be taken from there and placed anywhere.

FoX-config takes the following arguments:

For compiling files against FoX, do the following:

f95 -c `FoX-config --fcflags` sourcefile.f90

For linking objects to the FoX library, do:

f95 -o program `FoX-config --libs` *.o

or similar, according to your compilation scheme.

Note that by default, FoX-config assumes you are using all modules of the library. If you are only using part, then this can be specified by also passing the name of each module required, like so:

FoX-config --fcflags --wcml

Using FoX in your own project.

The recommended way to use FoX is to embed the full source code into an existing project.

(It would be possible to extract portions of the code, and embed just the ones that you need, but I recommend against it; it would be easy to lose parts of the code which are essential for generating good XML.)

In order to do this, you need to do something like the following:

  1. Put the full source code as a top-level subdirectory of the tree, called FoX. (you can of course delete the DoX/ and examples/ subdirectories if you wish to save space)
  2. Incorporate calls to FoX into the program.
  3. Incorporate building FoX into your build process.

To incorporate into the program

There is an example of suggested use in the examples/ subdirectory.

The easiest, and least intrusive way is probably to create a F90 module for your program, looking something like example_xml_module.f90

Then you must somewhere (probably in your main program), use this module, and call initialize_xml_output() at the start; and then end_xml_output() at the end of the program.

In any of the subroutines where you want to output data to the xml file, you should then insert use example_cml_moule at the beginning of the subroutine. You can then use any of the cml output routines with no further worries, as shown in the examples.

It is easy to make the use of FoX optional, by the use of preprocessor defines. This can be done simply by wrapping each call to your XML wrapper routines in #ifdef XML, or similar.

To incorporate into the build process:

If you have some sort of automatic Makefile configuration; for picking up which compiler to use, etc. then within whatever script you use to do this, you should insert a sequence of commands like:

(cd FoX; config/configure; cd ..)

This will instruct FoX to perform its own automatic configuration process.

Within the Makefile itself, you need to alter your compiler flags in the following fashion. Assuming that you have some sort of FFLAGS Makefile variable, then it should be amended like so:

FFLAGS="$(FFLAGS) `FoX/FoX-config --fcflags`"

You must also alter the linking step to include the FoX subroutines Again, assuming that you have some sort of variable LDFLAGS holding your linking flags, then it should be amended like so:

LDFLAGS="$(LDFLAGS) `FoX/FoX-config --libs`"

If you don't have any automatic Makefile configuration, and rely on the user making hand-edited changes to Makefiles, then you must add to your documentation how to configure & build FoX.


FoX_common

FoX_common is a module exporting interfaces to a set of convenience functions common to all of the FoX modules, which are of more general use.

Currently, the only publically available function is str, which converts primitive datatypes into strings in a consistent fashion, conformant with the expectations of XML processors.

It is fully described in StringFormatting


String handling in FoX

Many of the routines in wxml, and indeed in wcml which is built on top of wxml, are overloaded so that data may be passed to the same routine as string, integer, logical or real data.

In such cases, a few notes on the conversion of non-textual data to text is on order. The standard Fortran I/O formatting routines do not offer the control required for useful XML output, so FoX performs all its own formatting.

This formatting is done internally through a function which is also available publically to the user, str.

To use this in your program, import it via:

use FoX_common, only; str

and use it like so:

 print*, str(data)

You may pass data of the following primitive types to str:

Scalar data

Character (default kind)

Character data is returned unchanged.

Logical (default kind)

Logical data is output such that True values are converted to the string 'true', and False to the string 'false'.

Integer (default kind)

Integer data is converted to the standard decimal representation.

Real numbers (single and double precision)

Real numbers, both single and double precision, are converted to strings in one of two ways, with some control offered to the user. The output will conform to the real number formats specified by XML Schema Datatypes.

This may be done in one of two ways:

  1. Exponential notation, with variable number of significant figures. Format strings of the form "sn" are accepted, where n is the number of significant figures.

    Thus the number 111, when output with various formats, will produce the following output:

s1 1e2
s2 1.1e2
s3 1.11e2
s4 1.110e2

The number of significant figures should lie between 1 and the number of digits precision provided by the real kind. If a larger or smaller number is specified, output will be truncated accordingly. If unspecified, then a sensible default will be chosen.

This format is not permitted by XML Schema Datatypes 1.0, though it is in 2.0

  1. Non-exponential notation, with variable number of digits after the decimal point. Format strings of the form "rn", where n is the number of digits after the decimal point.

    Thus the number 3.14159, when output with various formats, will produce the following output:

r0 3
r1 3.1
r2 3.14
r3 3.142

The number of decimal places must lie between 0 and whatever would output the maximum digits precision for that real kind. If a larger or smaller number is specified, output will be truncated accorsingly. If unspecified, then a sensible default will be chosen.

This format is the only one permitted by XML Schema Datatypes 1.0

If no format is specified, then a default of exponential notation will be used.

If a format is specified not conforming to either of the two forms above, a run-time error will be generated.

NB Since by using FoX or str, you are passing real numbers through various functions, this means that they must be valid real numbers. A corollary of this is that if you pass in +/-Infinity, or NaN, then the behaviour of FoX is unpredictable, and may well result in a crash. This is a consequence of the Fortran standard, which strictly disallows doing anything at all with such numbers, including even just passing them to a subroutine.

Arrays and matrices

All of the above types of data may be passed in as arrays and matrices as well. In this case, a string containing all the individual elements will be returned, ordered as they would be in memory, each element separated by a single space.

If the data is character data, then there is an additional option to str, delimiter which may be any single-character string, and will replace a space as the delimiter.

wxml/wcml wrappers.

All functions in wxml which can accept arbitrary data (roughly, wherever you put anything that is not an XML name; attribute values, pseudo-attribute values, character data) will take scalars, arrays, and matrices of any of the above data types, with fmt= and delimiter= optional arguments where appropriate.

Similarly, wcml functions which can accept varied data will behave similarly.


WXML

wxml is a general Fortran XML output library. It offers a Fortran interface, in the form of a number of subroutines, to generate well-formed XML documents. Almost all of the XML features described in XML11 and Namespaces are available, and wxml will diagnose almost all attempts to produce an invalid document. Exceptions below describes where wxml falls short of these aims.

First, Conventions describes the conventions use in this document.

Then, Functions lists all of wxml's publically exported functions, in three sections:

  1. Firstly, the very few functions necessary to create the simplest XML document, containing only elements, attributes, and text.
  2. Secondly, those functions concerned with XML Namespaces, and how Namespaces affect the behaviour of the first tranche of functions.
  3. Thirdly, a set of more rarely used functions required to access some of the more esoteric corners of the XML specification.

Please note that where the documentation below is not clear, it may be useful to look at some of the example files. There is a very simple example in the examples/ subdirectory, but which nevertheless shows the use of most of the features you will use.

A more elaborate example, using almost all of the XML features found here, is available in the top-level directory as wxml_example.f90. It will be automatically compiled as part of the build porcess.

Conventions and notes:

Conventions used below.

Note that where strings are passed in, they will be passed through entirely unchanged to the output file - no truncation of whitespace will occur.

It is strongly recommended that the functions be used with keyword arguments rather than replying on implicit ordering.

Derived type: xmlf_t

This is an opaque type representing the XML file handle. Each function requires this as an argument, so it knows which file to operate on. (And it is an output of the xml_OpenFile subroutine) Since all subroutines require it, it is not mentioned below.

Function listing

Frequently used functions

Open a file for writing XML

By default, the XML will have no extraneous text nodes. This has the effect of it looking slightly ugly, since there will be no newlines inserted between tags.

This behaviour can be changed to produce slightly nicer looking XML, by switching on broken_indenting. This will insert newlines and spaces between some tags where they are unlikely to carry semantics. Note, though, that this does result in the XML produced being not quite what was asked for, since extra characters and text nodes have been inserted.

NB: The replace option should be noted. By default, xml_OpenFile will fail with a runtime error if you try and write to an existing file. If you are sure you want to continue on in such a case, then you can specify **replace**=.true. and any existing files will be overwritten. If finer granularity is required over how to proceed in such cases, use the Fortran inquire statement in your code. There is no 'append' functionality by design - any XML file created by appending to an existing file would almost certainly be invalid.

Close an opened XML file, closing all still-opened tags so that it is well-formed.

Open a new element tag

Close an open tag

Add an attribute to the currently open tag.

By default, if the attribute value contains markup characters, they will be escaped automatically by wxml before output.

However, in rare cases you may not wish this to happen - if you wish to output Unicode characters, or entity references. In this case, you should set escape=.false. for the relevant subroutine call. Note that if you do this, no checking on the validity of the output string iis performed; the onus is on you to ensure well-formedness

The value to be added may be of any type; it will be converted to text according to FoX's formatting rules, and if it is a 1- or 2-dimensional array, the elements will all be output, separated by spaces (except if it is a character array, in which case the delimiter may be changed to any other single character using an optional argument).

Add text data. The data to be added may be of any type; they will be converted to text according to FoX's formatting rules, and if they are a 1- or 2-dimensional array, the elements will all be output, separated by spaces (except if it is a character array, in which case the delimiter may be changed to any other single character using an optional argument).

Namespace-aware functions:

Add an XML Namespace declaration. This function may be called at any time, and its precise effect depends on when it is called; see below

Undeclare an XML namespace. This is equivalent to declaring an namespace with an empty URI, and renders the namespace ineffective for the scope of the declaration. For explanation of its scope, see below.

NB Use of xml_UndeclareNamespace implies that the resultant document will be compliant with XML Namespaces 1.1, but not 1.0; wxml will issue an error when trying to undeclare namespaces under XML 1.0.

Scope of namespace functions

If xml_[Un]declareNamespace is called immediately prior to an xml_NewElement call, then the namespace will be declared in that next element, and will therefore take effect in all child elements.

If it is called prior to an xml_NewElement call, but that element has namespaced attributes

To explain by means of example: In order to generate the following XML output:

 <cml:cml xmlns:cml="http://www.xml-cml.org/schema"/>

then the following two calls are necessary, in the prescribed order:

  xml_AddNamespace(xf, 'cml', 'http://www.xml-cml.org')
  xml_NewElement(xf, 'cml:cml')

However, to generate XML input like so: that is, where the namespace refers to an attribute at the same level, then as long as the xml_AddNamespace call is made before the element tag is closed (either by xml_EndElement, or by a new element tag being opened, or some text being added etc.) the correct XML will be generated.

Two previously mentioned functions are affected when used in a namespace-aware fashion.

The element or attribute name is checked, and if it is a QName (ie if it is of the form prefix:tagName) then wxml will check that prefix is a registered namespace prefix, and generate an error if not.

More rarely used functions:

If you don't know the purpose of any of these, then you don't need to.

Add XML declaration to the first line of output. If used, then the file must have been opened with addDecl = .false., and this must be the first wxml call to the document.o

NB The only XML versions available are 1.0 and 1.1. Attempting to specify anything else will result in an error. Specifying version 1.0 results in additional output checks to ensure the resultant document is XML-1.0-conformant.

NB Note that if the encoding is specified, and is specified to not be UTF-8, then if the specified encoding does not match that supported by the Fortran processor, you may end up with output you do not expect.

Add an XML document type declaration. If used, this must be used prior to first xml_NewElement call, and only one such call must be made.

Define an internal entity for the document. If used, this call must be made after xml_AddDOCTYPE and before the first xml_NewElement call.

Define an external entity for the document. If used, this call must be made after xml_AddDOCTYPE and before the first xml_NewElement call.

Define a parameter entity for the document. If used, this call must be made after xml_AddDOCTYPE and before the first xml_NewElement call.

Define a notation for the document. If used, this call must be made after xml_AddDOCTYPE and before the first xml_NewElement call.

Since there is no other method of adding ELEMENT or ATTLIST declarations to the DTD, this function provides a method to output arbitrary data to the DTD if such declarations are needed. Note that no checking at all is performed on the validity of string. Use this function with a great deal of care.

If used, this call must be made after xml_AddDOCTYPE and before the first xml_NewElement call.

Add XML stylesheet processing instruction, as described in [Stylesheets]. If used, this call must be made before the first xml_NewElement call.

Add an XML Processing Instruction.

If data is present, nothing further can be added to the PI. If it is not present, then pseudoattributes may be added using the call below. Normally, the name is checked to ensure that it is XML-compliant. This requires that PI targets not start with [Xx][Mm][Ll], because such names are reserved. However, some are defined by later W3 specificataions. If you wish to use such PI targets, then set xml=.true. when outputting them.

The output PI will look like: <?name data?>

Add a pseudoattribute to the currently open PI

Add an XML comment

This may be used anywhere that xml_AddCharacters may be, and will insert an entity reference into the contents of the XML document at that point. Note that if the entity inserted is a character entity, its validity well be checked according to the rules of XML-1.1, not 1.0.

If the entity reference is not a character entity, then no check is made of its validity, and a warning will be issued

Functions to query XML file objects

These functions may be of use in building wrapper libraries:

Return the filename of an open XML file

Return the currently open tag of the current XML file (or the empty string if none is open)

Exceptions

Below are explained areas where wxml fails to implement the whole of XML 1.0/1.1; numerical references below are to the sections in [XML11]]. These are divided into two lists:

Ways in which wxml renders it impossible to produce a certain sort of well-formed XML document:

  1. XML documents which are not namespace-valid may not be produced; that is, attempts to produce documents which are well-formed according to [XML11] but not namespace-well-formed according to [Namespaces] will fail.
  2. Unicode support[[2.2]](http://www.w3.org/TR/xml11/#charsets) is limited. Due to the limitations of Fortran, wxml will directly only emit characters within the range of the local single-byte encoding. wxml will ensure that characters corresponding to those in 7-bit ASCII are output correctly for a UTF-8 encoding. Any other characters are output without any transcoding, and a warning will be issued. Proper output of other unicode characters is possible through the use of character entities, but only where character data is allowed. No means is offered for output of unicode in XML Names. Unicode character references in the range 0-128 are checked before output according to the constraints of [XML10] or [XML11] as appropriate, but characters above 128 are not checked.
  3. DTD support is not complete. While a DTD may be output, and entities defined in the internal subset, there is no direct support for adding Element[3.2] or Attlist[[3.3](http://www.w3.org/TR/xml11/#attdecls] declarations; nor is there any direct support for Conditional Sections.[3.4] However, arbitrary strings may be added to the DTD, though without any checking for validity.
  4. Entity support is not complete[4.1, 4.2. 4.3]. All XML entities (parameter, internal, external) may be defined; however, general entities may only be referenced from within a character data section between tags generated with xml_NewElement, or within an element attribute value. (In principle it should be possible to start the root element from within an entity reference).
  5. Due to the constraints of the Fortran IO specification, it is impossible to output arbitrary long strings without carriage returns. The size of the limit varies between processors, but may be as low as 1024 characters. To avoid overrunning this limit, wxml will by default insert carriage returns before every new element, and if an unbroken string of attribute or text data is requested greater than 1024 characters, then carriage returns will be inserted as appropriate; within whitespace if possible; to ensure it is broken up into smaller sections to fit within the limits. Thus unwanted text sections are being created, and user output modified.

wxml will try very hard to ensure that output is well-formed. However, it is possible to fool wxml into producing ill-formed XML documents. Avoid doing so if possible; for completeness these ways are listed here. In all cases where ill-formedness is a possibility, a warning will be issued.

  1. If you specify a non-default text encoding, and then run FoX on a platform which does not use this encoding, then the result will be nonsense, and more than likely ill-formed. FoX will issue a warning in this case.
  2. Although entities may be output, their contents are not comprehensively checked. It is therefore possible to output combinations of entities which produce nonsense when referenced and expanded. FoX will issue a warning when this is possible.
  3. When entity references are made, a check is performed to ensure that the referenced entity exists - but if not it may be an externally-defined reference, in which case the document may or may not be ill-formed. If so, then a warning will be issued.
  4. When adding text through xml_AddCharacters, or as the value of an attribute, if any characters are passed in which are not within 7-bit ASCII, then the results are processor-dependent, and may result in an invalid document on output. A warning will be issued if this occurs. If you need a guarantee that such characters will be passed correctly, use character entities.
  5. In order to add non-ASCII characters to an attribute value via character entity references, the function xml_AddAttribute can be told not to escape its input. In this case, however, no checking at all is performed on the validity of the output string. A warning will be issued if this is done.
  6. In order to add ELEMENT and ATTLIST portions of the DTD, a function xml_AddStringToDTD is provided. However, no checking at all is done on the contents of the string passed in, so if that string is not a well-formed DTD fragment, the resultant document will be ill-formed. A warning will be issued if this is done/

Finally, it should be noted (although it is obvious from the above) that wxml makes no attempt at all to ensure that output documents are valid XML (by any definition of valid.)

References

[XML10]: W3C Recommendation, http://www.w3.org/TR/REC-xml/

[XML11]: W3C Recommendation, http://www.w3.org/TR/xml11

[Namespaces]: W3C Recommendation, http://www.w3.org/TR/xml-names11

[Stylesheets]: W3C Recommendation, http://www.w3.org/TR/xml-stylesheet


WCML

WCML is a library for outputting CML data. It wraps all the necessary XML calls, such that you should never need to touch any WXML calls when outputting CML.

The CML output is conformant to version 2.4 of the CML schema.

The available functions and their intended use are listed below. Quite deliberately, no reference is made to the actual CML output by each function.

Wcml is not intended to be a generalized Fortran CML output layer. rather it is intended to be a library which allows the output of a limited set of well-defined syntactical fragments.

Further information on these fragments, and on the style of CML generated here, is available at http://www.uszla.me.uk/specs/subset.html.

This section of the manual will detail the available CML output subroutines.

Use of WCML

wcml subroutines can be accessed from within a module or subroutine by inserting

 use FoX_wcml

at the start. This will import all of the subroutines described below, plus the derived type xmlf_t needed to manipulate a CML file.

No other entities will be imported; public/private Fortran namespaces are very carefully controlled within the library.

Dictionaries.

The use of dictionaries with WCML is strongly encouraged. (For those not conversant with dictionaries, a fairly detailed explanation is available at http://www.xml-cml.org/information/dictionaries)

In brief, dictionaries are used in two ways.

Identification

Firstly, to identify and disambiguate output data. Every output function below takes an optional argument, dictRef="". It is intended that every piece of data output is tagged with a dictionary reference, which will look something like nameOfCode:nameOfThing.

So, for example, in SIESTA, all the energies are output with different dictRefs, looking like: siesta:KohnShamEnergy, or siesta:kineticEnergy, etc. By doing this, we can ensure that later on all these numbers can be usefully identified.

We hope that ultimately, dictionaries can be written for codes, which will explain what some of these names might mean. However, it is not in any way necessary that this be done - and using dictRef attributes will help merely by giving the ability to disambiguate otherwise indistinguishable quantities.

We strongly recommend this course of action - if you choose to do follow our recommendation, then you should add a suitable Namespace to your code. That is, immediately after cmlBeginFile and before cmlStartCml, you should add something like:

call cmlAddNamespace('nameOfCode', 'WebPageOfCodee')

Again, for SIESTA, we add:

call cmlAddNamespace('siesta, 'http://www.uam.es/siesta')

If you don't have a webpage for your code, don't worry; the address is only used as an identifier, so anything that looks like a URL, and which nobody else is using, will suffice.

Quantification

Secondly, we use dictionaries for units. This is compulsory (unlike dictRefs above). Any numerical quantity that is output through cmlAddProperty or cmlAddParameter is required to carry units. These are added with the units="" argument to the function. In addition, every other function below which will take numerical arguments also will take optional units, although default will be used if no units are supplied.

Further details are supplied in section Units below.

General naming conventions for functions.

Functions are named in the following way:

Conventions used below.

Note that where strings are passed in, they will be passed through entirely unchanged to the output file - no truncation of whitespace will occur.

Also note that wherever a real number can be passed in (including through anytype) then the formatting can be specified using the conventions described in StringFormatting

Where an array is passed in, it may be passed either as an assumed-shape array; that is, as an F90-style array with no necessity for specifying bounds; thusly:

integer :: array(50)
call cmlAddProperty(xf, 'coords', array)

or as an assumed-size array; that is, an F77-style array, in which case the length must be passed as an additional parameter:

integer :: array(*)
call cmlAddProperty(xf, 'coords', array, nitems=50)

Similarly, when a matrix is passed in, it may be passed in both fashions:

integer :: matrix(50, 50)
call cmlAddProperty(xf, 'coords', matrix)

or

integer :: array(3, *)
call cmlAddProperty(xf, 'coords', matrix, nrows=3, ncols=50)

All functions take as their first argument an XML file object, whose keyword is always xf. This file object is initialized by a cmlBeginFile function.

It is highly recommended that subroutines be called with keywords specified rather than relying on the implicit ordering of arguments. This is robust against changes in the library calling convention; and also stepsides a significant cause of errors when using subroutines with large numbers of arguments.

Units

Note below that the functions cmlAddParameter and cmlAddProperty both require that units be specified for any numerical quantities output.

If you are trying to output a quantity that is genuinely dimensionless, then you should specify units="units:dimensionless"; or if you are trying to output a countable quantity (eg number of CPUs) then you may specify units="units:countable".

For other properties, all units should be specified as namespaced quantities. If you are using a very few common units, it may be easiest to borrow definitions from the provided dictionaries;

(These links do not resolve yet.)

cmlUnits: http://www.xml-cml.org/units/units
siUnits: http://www.xml-cml.org/units/siUnits
atomicUnits: http://www.xml-cml.org/units/atomic

Otherwise, you should feel at liberty to construct your own namespace; declare it using cmlAddNamespace, and markup all your units as:

 units="myNamespace:myunit"

Functions for manipulating the CML file:

This takes care of all calls to open a CML output file.

This takes care of all calls to close an open CML output file, once you have finished with it. It is compulsory to call this - if your program finished without calling this, then your CML file will be invalid.

This adds a namespace to a CML file.
NB This may only ever be called immediately after a cmlBeginCml call, before any output has been performed. Attempts to do otherwise will result in a runtime error.

This will be needed if you are adding dictionary references to your output. Thus for siesta, we do:

call cmlAddNamespace(xf, 'siesta', 'http://www.uam.es/siesta')

and then output all our properties and parameters with dictRef="siesta:something".

This pair of functions begin and end the CML output to an existing CML file. It takes care of namespaces.

Note that unless specified otherwise, there will be a convention attribute added to the cml tag specifying FoX_wcml-2.0 as the convention. (see http://www.uszla.me.uk/FoX for details)

Start/End sections

This pair of functions open & close a metadataList, which is a wrapper for metadata items.

This pair of functions open & close a parameterList, which is a wrapper for input parameters.

This pair of functions open & close a propertyList, which is a wrapper for output properties.

Start/end a list of bands (added using cmlAddBand below)

Start/end a list of k-points (added using cmlAddKpoint below)

Note that in most cases where you might want to use a serial number, you should probably be using the cmlStartStep subroutine below.

This pair of functions open & close a module of a computation which is unordered, or loosely-ordered. For example, METADISE uses one module for each surface examined.

This pair of functions open and close a module of a computation which is strongly ordered. For example, DLPOLY uses steps for each step of the simulation.

Adding items.

This adds a single item of metadata. It takes the following arguments:

This function adds a tag representing an input parameter

This function adds a tag representing an output property

Outputs an atomic configuration.

Outputs information about a unit cell, in lattice-vector form

Outputs information about a unit cell, in crystallographic form

Output eigenvalues for a band.

Output a k-point

Output a set of eigenvalues and eigenvectors

Common arguments

All cmlAdd and cmlStart routines take the following set of optional arguments:


Debugging with FoX.

Following experience integrating FoX into several codes, here are a few tips for debugging any problems you may encounter.

Compilation problems

You may encounter problems at the compiling or linking stage, with error messages along the lines of: 'No Specific Function can be found for this Generic Function' (exact phrasing depending on compiler, of course.)

If this is the case, it is possible that you have accidentally got the arguments to the offending out of order. If so, then use the keyword form of the argument to ensure correctness; that is, instead of doing:

call cmlAddProperty(file, name, value)

do:

call cmlAddProperty(xf=file, name=name, value=value)

This will prevent argument mismatches, and is recommended practise in any case.

Runtime problems

You may encounter run-time issues. FoX performs many run-time checks to ensure the validity of the resultant XML code. In so far as it is possible, FoX will either issue warnings about potential problems, or try and safely handle any errors it encounters. In both cases, warning will be output on stderr, which will hopefully help diagnose the problem.

Sometimes, however, FoX will encounter a problem it can do nothing about, and must stop. In all cases, it will try and write out an error message highlighting the reason, and generate a backtrace pointing to the offending line. Occasionally though, the compiler will not generate this information, and the error message will be lost.

If this is the case, you can either investigate the coredump to find the problem, or (if you are on a Mac) look in ~/Library/Logs/CrashReporter to find a human-readable log.

If this is not enlightening, or you cannot find the problem, then some of the most common issues we have encountered are listed below. Many of them are general Fortran problems, but sometimes are not easily spotted in the context of FoX.

Incorrect formatting.

Make sure, whenever you are writing out a real number through one of FoX's routines, and specifying a format, that the format is correct according to StringFormatting. Fortran-style formats are not permitted, and will cause crashes at runtime.

Array overruns

If you are outputting arrays or matrices, and are doing so in the traditional Fortran style - by passing both the array and its length to the routine, like so:

 call xml_AddAttribute(xf=file, name=name, value=array, nvalue=n)

then if n is wrong, you may end up with an array overrun, and cause a crash.

We highly recommend wherever possible using the Fortran-90 style, like so:

 call xml_AddAttribute(xf=file, name=name, value=array)

where the array length will be passed automatically.

Uninitialized variables

If you are passing variables to FoX which have not been initialized, you may well cause a crash. This is especially true, and easy to cause if you are passing in an array which (due to a bug elsewhere) has been partly but not entirely initialized. To diagnose this, try printing out suspect variables just before passing them to FoX, and look for suspiciously wrong values.

Invalid floating point numbers.

If during the course of your calculation you accidentally generate Infinities, or NaNs, then passing them to any Fortran subroutine can result in a crash - therefore trying to pass them to FoX for output may result in a crash.

If you suspect this is happening, try printing out suspect variables before calling FoX.


Further information

FoX evolved from the initial codebase of xmlf90, which was written largely by Alberto Garcia <albertog@icmab.es> and Jon Wakelin <jon.wakelin@bristol.ac.uk>.

FoX is the work of Toby White <tow21@cam.ac.uk>, and all bug reports/complaints/bouquets of roses should be sent to him.

There is a FoX website at http://www.uszla.me.uk/software/FoX/.

There is also a mailing list for announcements/queries/bug reports. Information on how to subscribe may be found at http://www.uszla.me.uk/cgi-bin/mailman/listinfo/FoX/,

This manual is © Toby White 2006.


Licensing

FoX is licensed under the agreement below. This is intended to make it as freely available as possible, subject only to retaining copyright notices and acknowledgements.

If for any reason this license causes issues with your intended use of the code, please contect the author.

The license can also be found within the distributed source, in the file FoX/LICENSE

Copyright:
© 2003, 2004, Alberto Garcia, Jon Wakelin
© 2005, 2006, Toby White
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE