Jumbo90

What is Jumbo90?

• Jumbo90 is a CML formatting Library for Fortran, it provides:
• Convenience routines to write complete CML elements
• Convenience routines to write complete STMML elements
• Optional Indentation of output
• Checks that tags are properly balanced
• Checks that attribute names are well formed (i.e. contain only [A-Z a-z 0-9 _ -] and start with [A-Z a-z _]).
  • The colon is allowed but should be reserved for namespacing so an error is flagged if more than one colon is present in attribute name
• Checks if attribute values contain predefined entities (<, >, &, ', ")
• Checks for duplicate attribute names

How to use Jumbo90

Jumbo covers CML, STMML and basic XML. Below is the full list of subroutine names, followed by the arguments they take. Whenever writing a real*8 or real*4 you can always pass an optional format argument, e.g.

	
	call xml_AddAttribute(file, 'martin','height', 32.1285)
	call xml_AddAttribute(file, 'martin','height', 32.1285, '(f6.2)')

would add an "height" attribute with a value of "32.1285" to a "martin" element . In the first case the default format '(f8.3)' would be used, in the second case the user supplied format '(f6.2)' would be used. Many subroutines can take a number of optional arguments (reflecting the CML schema) therefore the longer 'argument=value' format should be use when calling these subroutines, e.g.,

	call xml_OpenFile('myFile.xml', file)

Notes:

Jumbo90 is based on an earlier fortran 77 program called Jumbo77, which was itself based on an existing Java CML parser called JUMBO written by Peter Murray-Rust. Jumbo90 is now built in a modular fashion allowing output of basic XML, STMML and CML. The STMML layer builds on the XML. The CML layer, in turn, builds on the STMML layer. The base XML writing utilities are now provided by FLIB_XMLWRITE, a set of F90 modules written by Alberto Garcia.

Routines

General routines

1. xml_OpenFile - Mandatory Initialization routine
2. xml_Close - Mandatory finalization routine, closes channels, etc
3. str - utility to convert, floats and integers to character strings

XML routines

1. xml_NewElement - writes an xml start tag
2. xml_AddAttribute - adds an attribute to a tag
3. xml_AddPcdata - adds text to an xml element
4. xml_EndElement - writes an xml end tag

STMML routines

1. stmAddStartTag
2. stmAddScalar
3. stmAddArray
4. stmAddMatrix
5. stmAddTriangle
6. stmError
7. stmMessage
8. stmWarning

CMLCore routines

1. cmlAddMolecule - adds a complete CML <molecule> element
2. cmlAddAtom - adds a CML <atom> start tag
3. cmlAddCoordinates - adds coordinate attributes to an <atom> tag
4. cmlAddCrystal - adds a complete CML <crystal> element
5. cmlAddMetadata - adds a complete CML <metadata> element
6. cmlAddLength(length, id, atomRef1, atomRef2, fmt)
7. cmlAddAngle(angle, id, atomRef1, atomRef2, atomRef3, fmt)
8. cmlAddTorsion(torsion, id, atomRef1, atomRef2, atomRef3, atomRef4, fmt)
9. cmlAddEigenvalue(n, dim, eigvec, eigval, id, title, dictRef, fmt)

CMLComa routines (Condensed Matter)

1. cmlAddLattice - write a complete lattice element
2. cmlAddProperty - write a complete property element, containing scalar, array (vector) or matrix value (i.e. it has several interfaces)
3. cmlAddParameter - adds a complete CML <parameter> element

Subroutine Guide

1. xml_OpenFile(filename, ind, xf)

   argument	role	type	optional	default
   filename	xml filename	character(len=*)	no
   ind	controls indentation of output	logical	yes	.true.
   xf	xml filename	type(xmlf_t)	no

2. xml_Close(filehandle)

   argument	role	type	optional	default
   xf	xml filehandle	type(xmlf_t)	no

3. function str(value, format)

   argument	role	type	optional	default
   value	value to convert to string	real*8, real*4, integer	no
   format	format for reals	character(len=*)	yes	g22.12

   ---

1. xml_NewElement(xf, name)

   argument	role	type	optional	default
   xf	xml filehandle	type(xmlf_t)	no
   name	name of tag to add	character(len=*)	no

2. xml_AddAttribute(xf, name, attname, value)

   argument	role	type	optional	default
   xf	xml filehandle	type(xmlf_t)	no
   name	name of tag	character(len=*)	no
   attname	attribute name	character(len=*)	no
   value	attribute value	character(len=*) | integer | real*8 | real*4	no
   fmt	format for reals	character(len=*)	yes	f8.3

3. xml_AddPcdata(xf, value)

   argument	role	type	optional	default
   xf	xml filehandle	type(xmlf_t)	no
   value	string to add	character(len=*) | integer | real*8 | real*4	no
   fmt	format for reals	character(len=*)	yes	f8.3

4. xml_EndElement(xf, name)

   argument	role	type	optional	default
   xf	xml filehandle	type(xmlf_t)	no
   name	name of element to close	character(len=*)	no

---

1. stmAddStartTag(xf, name, id, title, dictref)

   argument	role	type	optional	default
   xf	xml filehandle	type(xmlf_t)	no
   name	tag name	character(len=*)	no
   id	unique id	character(len=*)	yes
   title	tag description	character(len=*)	yes
   dictref	dictionary reference	character(len=*)	yes

2. stmAddScalar(xf, value, id, title, dictref, type, fmt)

   argument	role	type	optional	default
   xf	xml filehandle	type(xmlf_t)	no
   value	the scalar value	character(len=*) | integer | real*8 | real*4	no
   id	unique id	character(len=*)	yes
   title	tag description	character(len=*)	yes
   dictref	dictionary reference	character(len=*)	yes
   fmt	format for reals	character(len=*)	yes	f8.3

3. stmAddArray(xf, nvalue, array, id, title, dictref, type|units, delim|fmt)

   argument	role	type	optional	default
   xf	xml filehandle	type(xmlf_t)	no
   nvalue	length of array	integer	no
   array	the array	character(len=*) | integer | real*8 | real*4	no
   id	unique id	character(len=*)	yes
   title	tag description	character(len=*)	yes
   dictref	dictionary reference	character(len=*)	yes
   fmt	format for reals	character(len=*)	yes	f8.3

4. stmAddMatrix(xf, nrows, ncols, dim, matrix, id, title, dictref, units, fmt)

   argument	role	type	optional	default
   xf	xml filehandle	type(xmlf_t)	no
   nrows	number of rows	integer	no
   ncols	number of columns	integer	no
   dim	fastest dimension	integer	no
   matrix	the matrix	character(len=*) | integer | real*8 | real*4	no
   id	unique id	character(len=*)	yes
   title	tag description	character(len=*)	yes
   dictref	dictionary reference	character(len=*)	yes
   fmt	format for reals	character(len=*)	yes	f8.3

5. stmAddTriangle(xf, nvalue, array, id, title, dictref, units, fmt)

   argument	role	type	optional	default
   xf	xml filehandle	type(xmlf_t)	no
   nvalue	length of array	integer	no
   array	the array	character(len=*) | integer | real*8 | real*4	no
   id	unique id	character(len=*)	yes
   title	tag description	character(len=*)	yes
   dictref	dictionary reference	character(len=*)	yes
   fmt	format for reals	character(len=*)	yes	f8.3

6. stmAddError(xf, msg, id, title, dictRef)

   argument	role	type	optional	default
   xf	xml filehandle	type(xmlf_t)	no
   msg	length of array	character(len=*)	no
   id	unique id	character(len=*)	yes
   title	tag description	character(len=*)	yes
   dictref	dictionary reference	character(len=*)	yes

7. stmAddMessage(xf, msg, id, title, dictRef)

   argument	role	type	optional	default
   xf	xml filehandle	type(xmlf_t)	no
   msg	length of array	character(len=*)	no
   id	unique id	character(len=*)	yes
   title	tag description	character(len=*)	yes
   dictref	dictionary reference	character(len=*)	yes

8. stmAddWarning(xf, msg, id, title, dictRef)

   argument	role	type	optional	default
   xf	xml filehandle	type(xmlf_t)	no
   msg	length of array	character(len=*)	no
   id	unique id	character(len=*)	yes
   title	tag description	character(len=*)	yes
   dictref	dictionary reference	character(len=*)	yes

---

1. cmlAddMolecule(xf, natoms, elements, coords, style, id, title, dictref, fmt)

   argument	role	type	optional	default
   xf	xml filehandle	type(xmlf_t)	no
   natoms	number of atoms	integer	no
   elements(natoms)	list of atomic symbols	character(len=2)	no
   coords(3, natoms)	atomic coordinates	real*8 | real*4	no
   style	CML output style (x3 | xFrac | xyz3 | xyzFrac)	character(len=*)	yes	x3
   id	unique id	character(len=*)	yes
   title	tag description	character(len=*)	yes
   dictref	dictionary reference	character(len=*)	yes
   fmt	format for reals	character(len=*)	yes	f8.3

2. cmlAddAtom(xf, elem, id, charge, hCount, occupancy, fmt)

   argument	role	type	optional	default
   xf	xml filehandle	type(xmlf_t)	no
   elem	atomic symbol	character(len=2)	yes
   id	unique id	character(len=*)	yes
   charge	formal charge	integer	no
   hCount	hydrogen count	integer	no
   occupancy	site occupancy	real*8 | real*4	no
   fmt	format for occupancy	character(len=*)	yes	f8.3

3. cmlAddCoordinates(xf, x, y, z, style, fmt)

   argument	role	type	optional	default
   xf	xml filehandle	type(xmlf_t)	no
   x	x coordinate in cartesian format	real*8 | real*4	no
   y	y coordinate in cartesian format	real*8 | real*4	no
   z	z coordinate in cartesian format	real*8 | real*4	yes
   style	CML output style (x3 | xFrac | xyz3 | xyzFrac | xy2)	character(len=*)	yes	x3
   fmt	format for coordinates	character(len=*)	yes	f8.3

4. cmlAddcrystal(xf, a, b, c, alpha, beta, gamma, id, title, dictref, lenunits, angunits, fmt)

   argument	role	type	optional	default
   xf	xml filehandle	type(xmlf_t)	no
   a	lattice parameter a	real*8 | real*4	no
   b	lattice parameter b	real*8 | real*4	no
   c	lattice parameter c	real*8 | real*4	no
   alpha	lattice angle alpha	real*8 | real*4	no
   beta	lattice angle beta	real*8 | real*4	no
   gamma	lattice angle gamma	real*8 | real*4	no
   lenunits	units for lattice parameters	character(len=*)	yes	angstrom
   angunits	units for lattice angles	character(len=*)	yes	degree
   id	unique id	character(len=*)	yes
   title	tag description	character(len=*)	yes
   dictref	dictionary reference	character(len=*)	yes
   fmt	format for reals	character(len=*)	yes	f8.3

5. cmlAddMetadata(xf, name, content, conv)

   argument	role	type	optional	default
   xf	xml filehandle	type(xmlf_t)	no
   name	name (eg author)	character(len=*)	no
   content	value (eg Jon Wakelin)	character(len=*)	no
   conv	a convention	character(len=*)	yes

6. cmlAddLattice(xf, cell, units, title, id, dictref, conv, lattType, spaceType)

   argument	role	type	optional	default
   xf	xml filehandle	type(xmlf_t)	no
   cell(3,3)	the lattice vectors	real*8 | real*4	no
   units	units for lattice vectors	character(len=*)	yes
   title	tag description	character(len=*)	yes
   id	unique id	character(len=*)	yes
   dictref	dictionary reference	character(len=*)	yes
   conv	a convention	character(len=*)	yes	f8.3
   lattType	lattice type (primitive |full)	character(len=*)	yes
   spaceType	space type (real | reciprocal)	character(len=*)	yes

7. cmlAddProperty(xf, property, nvalues, ncols, nrows, dim, id, title, conv, dictref, ref, units, fmt)

   argument	role	type	optional	default
   xf	xml filehandle	type(xmlf_t)	no
   property	a scalar, array or matrix property. Yes it takes all three, but see next three arguments.	charcter(len=*) | integer | real*8 | real*4	no
   nvalue	number of value for vector	integer	no if writing a vector
   ncols	number of rows for matrix	integer	no if writing a matrix
   nrows	number of rows for matrix	integer	no if writing a matrix
   dim	number of the fastest growing dimension in the matrix	integer	yes
   id	unique id	character(len=*)	yes
   title	tag description	character(len=*)	yes
   conv	a convention	character(len=*)	yes
   dictref	dictionary reference	character(len=*)	yes
   ref	refernce to an atom (via the atom 'id' attribute)	character(len=*)	yes
   units	units for the property	character(len=*)	yes
   fmt	format for reals	character(len=*)	yes	f8.3

8. cmlAddParameter(xf, value, name, id, title, conv, cons, dictref, ref, role, units, fmt)

   argument	role	type	optional	default
   xf	xml filehandle	type(xmlf_t)	no
   value	the parameter	charcter(len=*) | integer | real*8 | real*4 | logical	no
   id	unique id	character(len=*)	yes
   title	tag description	character(len=*)	yes
   conv	a convention	character(len=*)	yes
   cons	a constraint	character(len=*)	yes
   role	the role of the parameter	character(len=*)	yes
   dictref	dictionary reference	character(len=*)	yes
   ref	refernce to an atom (via the atom 'id' attribute)	character(len=*)	yes
   units	units for the parameter	character(len=*)	yes
   fmt	format for reals	character(len=*)	yes	f8.3

CML output styles for coordinates

x3      = 3D Cartesian coordinates long format
xyz3    = 3D Cartesian coordinates short format
xFrac   = 3D fractional coordinates long format
xyzFrac = 3D fractional coordinates short format
xy2     = 2d Cartesian coordinates long format