CMISS Comment Specification

This document specifies the form of comments to be used to annonte the CMISS source in order that the information contained within the comments may be machine-parsed and extracted.

Recent Changes

Comment Prefixes

All comments in CMISS, whether they are to be parsed by external programs or not, follow normal Fortran conventions, so we differentiate our comments from normal comments by adopting a specific prefix for each line.

The convention is to have a line that starts with a normal Fortran Comment (i.e. a C at the beginning of the line) followed by either three or four hash ("#") symbols. Lines not starting with a comment and 3 or 4 hashes are simply ignored.

The style to be used within the CMISS source is to start a related group of comments with a 4 hash comment, and each subsequent line with a 3 hash comment. 

C#### Subroutine: ISORT
C###  Description:
C###    ISORT sorts N integer IDATA values into a non-decreasing 
C###    sequence using a bubble sort algorithm.

Tags

CMISS comments are made up of one or more tags. A tag consists of the tag name followed by a colon and then the tag body. A simple example is: 
C#### Variable: JTYP14

There are two features of tags that are slightly more comprex; multi-line tags, and embedded HTML inside tags.

Multiline Tags

Multiline Tags work by having every subsequent line after the first indented by one or more spaces (or tabs). Blank lines are acceptable, and are interpreated to mean a paragraph break. The multiline tag continues until a tagf is found with a line that isn't indented.

An simple example of a multiline tag is as follows: 

C#### Description:
C###    The coordinate position (in rectangular cartesian)
C###    are strored in XQ, including fibre angle and sheet
C###    angle information.
A more complicated exmaple of one single and one multiline tag: 
C#### Subtoutine: IPGRID
C###  Description:
C###    PGRID defines collocation grids na=1,NMGT (NMGT>1 for
C###    multigrid if ITYP4(nr,nx)=4). Steps through all elements,
C###    then through all gauss points in each element, defining a
C###    grid point for each unique gauss point (as gauss points on
C###    the boundary should only have one grid point, though they
C###    are shared between two elements. 
C###  
C###    After this, defines grid points to use for calculating
C###    no-flux boundary conditions at grid points on the external
C###    boundary of the mesh.
C###  
C###    Now also stores values of dx/dxi and dnu/dx for each gp in
C###    DXQ to be used later in the solution process. Coordinate
C###    position (in rectangular cartesian) is now stored in XQ,
C###    including fibre angle and sheet angle.

Embedded HTML Tags

HTML may also be used within tags, thus allowing full control over the final appearance of the text. This is useful for formatting blocks and tables of text, for lists and anything else that HTML provides control over (including embedded URL's).

To specify the body text of a tag as HTML, simple bracket the entire text with an <HTML> ... </HTML> pair as in the following example: 

C#### Description:
C###    <HTML>
C###    MESH3_NB(i,j) are the basis numbers used in the mesh.
C###    When j=1 the bases are BE bases. When j=2 the bases
C###    are FE bases.
C###    <UL>
C###    <LI>i=1 gives the main basis function number 
C###    <LI>i=2 gives the bottom sector (apex node 1) basis number
C###    <LI>i=3 gives the top sector (apex node 3) basis number
C###    </UL>
C###    </HTML>

Groups

A Group is a series of tags that describe a certain type of data. For example the Variable Group has tags that contain the name of the variable, a description, where the variable is set up, what type the variable is and possibly a list of related variables or routines that the user can also check.

Specific Groups

There are currently six groups defined for use in the CMISS source:

Each type of group has a set of rules that define what tags are part of that group. Some of the tags are optional, and some may occur more than one time. Each group starts with a "head" tag that defines which group the following tags belong to.

Module Group

The head tag of the module group is Module and the group must have one Description tag as well as an optional See-Also tag.
Tags:
Module - The name of the module, such as "FE10", or "FEUSER"
Description - A description of the module.
See-Also - A list of comma seperated names of other subroutines, modules, variables, or whatever that are related to the module. When viewing this list the user can click on any name and will be taken to the relevant information.
Routine - The name of a routine in the module. The format of the tag is a single word for the routine name followed by a simple one line description.
For example: 
C#### Module: FE07
C###  Description: Routines to solve fem and bem equations
C###  Routine: GETEIGENWORK    Allocates the eigenproblem work arrays
C###  Routine: SOLVE_SYSTEM    Solves a linear system of equations

Subroutine Group

The head tag of the subroutines group is Subroutine and the group must have one Description tag. Like the Module group above, the Subroutine Group may also have an optional See-Also tag.
Tags:
Subroutine - The name of the subroutine, such as "BASIS8" or "GINOUT"
Description - A description of the subroutine.
See-Also - A list of comma seperated names of other relavant information.
See-Example - A list of comma seperated names of relavant examples.
For example: 
C#### Subroutine: BASIS8 
C###  Description:
C###    BASIS8 supplements basis function array
C###    PG(ns,nu,ng,nb),ns=1,.NST(nb), with auxiliary
C###    functions ns=NST(nb) + na, where na=1,..NAT(nb), for use
C###    with element parameters
C###    ZA(na,nc,nh,ne).

Function Group

The head tag of the function group is Function, and the group must also include a Description tag. There are also four optional tags: Type, See-Also and Returns.
Tags:
Function - The name of the function, such as "FHN_ION" or "NULL"
Description - A description of the function.
Type - The type of the return data of the function.
See-Also - A list of comma seperated names of other relavant information. 
C#### Function: CHMESH_FX
C###  Type: REAL*8
C###  Description:
C###    CHMESH_FX is one of J Crocombe's (temporary) change 
C###    mesh functions.

Command Group

The command group's head tag is Command. It has a Description tag and an optional See-Also tag. In addition there can be one or more Parameter tags for each of the commands paramters.
Tags:
Command - The name of the command, such as "show reactions" or "export nodes"
Description - A description of the command.
See-Also - A list of comma seperated names of other relavant information.
Parameters - One or more different parameters for the command, such as "<in ELEMENTS>[all]" or "<geometry/fibre/field/sheet>[geometry]". If the Parameter tag is more than one line long, everything after the first line is considered a description for that parameter.
Examples: 
C#### Command: define data;m 
C###  Parameter: <geometry/fibre/field/sheet>[geometry]
C###             What sort of data to define.
C###  Parameter: <on WSS>[1]
C###             Which workstation (window) to display the information.
C###  Description:
C###    The same information as above can be entered using
C###    the mouse. The mouse is used to locate the positions
C###    of the data, and the value at the location is
C###    entered via the keyboard.

Variable Group

The variable group's head tag is Variable and it must also contain a Description tag. Optional tags for this group are Type, Set-Up and See-Also.
Tags:
Variable - The name of the variable, such as "EDD" or "NJ_FIT"
Description - A description of the variable.
See-Also - A list of comma seperated names of other relavant information.
Type - The type of the variable, whether it be INTEGER or REAL*8.
Set-Up - The routine in which the variable is set up.
Examples: 
C#### Variable: ITYP10(nr)
C###  Type: INTEGER
C###  Set_up: IPCOOR
C###  Description:
C###    ITYP10(nr) is 1..5 for coordinates rectangular
C###    cartesian/cylindrical polar/spherical polar/prolate
C###    spheroidal/oblate spheroidal.

Comment Group

Comments are groups of information that don't appear elsewhere, and generally describe some over all philosophy or structure within the code.
Tags:
Comment - The title of the comment, such as "SPARSITY STRUCTURES" or "BINARY FILE FORMAT"
Description - The descriptive text.
See-Also - A list of comma seperated names of other relavant information.
Examples: 
C#### Comment: FIBRE IMBRICATION and SHEET ANGLES
C###  Description:
C###    Eqtn 5 of "Laminar Structure of the Heart" by Le
C###    Grice, Hunter and Smaill defines how the fibre
C###    reference vectors F_VECTOR, G_VECTOR and H_VECTOR
C###    are computed from the microstructural material
C###    axis vectors A_VECTOR, B_VECTOR and C_VECTOR.
C###    Three successive coordinate rotations define the
C###    transformation (the order IS important). Firstly,
C###    the material vectors are rotated by GAMA-PI/2
C###    about the fibre axis until the new sheet axis lies
C###    in the Xi1-Xi2 plane. Secondly, the resulting
C###    vectors are rotated by BETA about the new sheet
C###    axis until the new fibre axis also lies in the
C###    Xi1-Xi2 plane. Lastly, the resulting vectors are
C###    rotated by ALFA about the new sheet-normal axis
C###    (which now coincides with the Xi1-Xi2 plane
C###    normal) until the new fibre axis coincides with
C###    the Xi1 base vector.

Block Data Group

The head tag of the block data group is BlockData and the group must have one Description tag.
Tags:
BlockData - The name of the block data.
Description - A description of the block data.
Examples: 
C#### BlockData: BLK30
C###  Description:
C###    BLK30 sets up parameter titles in common block

Appendix A: Comment Rule File

Each type of comment starts with a different tag, and contains differing, although sometime overlapping, tags inside them, some of which are optional and some of which are mandatory. Below is listed the rules file that the external programs use to parse the comments within CMISS. 
--
-- Rules for parsing the embedded comments within conforming files
-- (such as the CMISS FORTRAN source, etc)
--


-- Definition of CMISS comments -----------------------------------------------
--

define MODULE as
  <
  HEAD Module
  TAG  Description
  TAG  Routine[0..1]   -- Optional
  TAG  See-Also[0..1]  -- Optional
  >


define SUBROUTINE as
  <
  HEAD Subroutine
  TAG  Description
  TAG  See-Also[0..1]  -- See-Also is an optional element
  TAG  See-Example[0..1]  -- See-Example is an optional element
  >


define FUNCTION as
  <
  HEAD Function
  TAG  Description
  TAG  Type[0..1]      -- Optional
  TAG  Returns[0..1]   -- Optional
  TAG  See-Also[0..1]  -- Optional
  >


define COMMAND as
  <
  HEAD Command
  TAG  Description
  TAG  Parameter[0..N]  -- There can be zero, one, or more parameters
  TAG  See-Also[0..1]   -- Optional
  >


define VARIABLE as
  <
  HEAD Variable
  TAG  Description
  TAG  Type[0..1]      -- Optional
  TAG  Set-Up[0..1]    -- Where var is first set up (Optional)
  TAG  See-Also[0..1]  -- Optional
  >


define COMMENT as
  <
  HEAD Comment
  TAG  Description
  TAG  See-Also[0..1]  -- Optional
  >


define BlockData as
  <
  HEAD BlockData
  TAG  Description
  >

Further Examples

C#### Variable: JTYP14
C###  Type: INTEGER
C###  Set_up: IPMESH
C###  Description:
C###    <HTML>
C###    JTYP14 is mesh type for specialized meshes (1 = regular fractal
C###    tree; 2 = stochastic fractal tree) as follows:
C###    Fractal tree branch parameters:
C###    <UL>
C###    <LI>Ratio_Angle,Ratio_Length,Ratio_Diameter
C###    <LI>B_angle_y(no_gen) : mean angle branch makes with y-axis
C###    <LI>B_angle_xy(no_gen): mean angle branch makes with xy-plane
C###    <LI>B_angle_SD(no_gen): standard deviation of angles<BR>
C###    Note: angles are generated with Normal distribution using mean 
C###    and standard deviation obtained by dividing previous generation
C###    values by Ratio_Angle.<BR>
C###    <LI>B_length(no_gen)
C###    <LI>B_diameter(no_gen)
C###    <LI>B_volume(no_gen)
C###    <LI>B_flow(no_gen)   ?? <-- not needed
C###    <LI>NW(ne,1)=generation number
C###    </UL> 
C###    </HTML>
C#### Subroutine: IPGRID
C###  Description:
C###    IPGRID defines collocation grids na=1,NMGT (NMGT>1 for 
C###    multigrid if ITYP4(nr,nx)=4).  Steps through all elements, then 
C###    through all gauss points in each element, defining a grid point 
C###    for each unique gauss point (as gauss points on the boundary 
C###    should only have one grid point, though they are shared between 
C###    two elements.  After this, defines grid points to use for 
C###    calculating no-flux boundary conditions at grid points on the 
C###    external boundary of the mesh.  Now also stores values of 
C###    dx/dxi and dnu/dx for each gp in DXQ to be used later in the 
C###    solution process.  Coordinate position (in rectangular 
C###    cartesian) is now stored in XQ, including fibre angle and
C###    sheet angle.
C###  See-Also: ITYP4, XQ