# Jumbo90

##
1. 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

##
2. 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 (xmlf90-wxml), a set of F90 modules written by Alberto Garcia.

##
3. 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

##
4. 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