Source documentation format
<center><h1><i>CMISS Comment Specification</i></h1> </center>
<i> 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. </i><p> <i><b>Recent Changes</b> </i></p><ul><li><i>The <tt>Routine</tt> tag in the <tt>Module</tt> group. </i></li><li><i>Expanded behaviour of the <tt>Paramater</tt> tag in the <tt>Command</tt>
group.
</i></li></ul>
<p>
</p><hr>
<h3>Comment Prefixes</h3>
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.
<p>
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 ("<b>#</b>") symbols. Lines not starting with a comment and 3 or 4 hashes are simply ignored.
</p><p>
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.
</p><p>
</p><dl><dd> <pre>C#### Subroutine: ISORT<br>C### Description:<br>C### ISORT sorts N integer IDATA values into a non-decreasing <br>C### sequence using a bubble sort algorithm.<br></pre> </dd></dl>
<p>
</p><hr>
<h3>Tags</h3>
CMISS comments are made up of one or more <b>tags</b>. A tag consists of the tag name followed by a colon and then the tag body. A simple example is:
<dl><dd> <pre>C#### Variable: JTYP14<br></pre> </dd></dl>
<p>
There are two features of tags that are slightly more comprex; multi-line tags, and embedded HTML inside tags.
</p><p>
</p><h4>Multiline Tags</h4>
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.
<p>
An simple example of a multiline tag is as follows:
</p><dl><dd> <pre>C#### Description:<br>C### The coordinate position (in rectangular cartesian)<br>C### are strored in XQ, including fibre angle and sheet<br>C### angle information. <br></pre> </dd></dl>
A more complicated exmaple of one single and one multiline tag: <dl><dd> <pre>C#### Subtoutine: IPGRID<br>C### Description:<br>C### PGRID defines collocation grids na=1,NMGT (NMGT>1 for<br>C### multigrid if ITYP4(nr,nx)=4). Steps through all elements,<br>C### then through all gauss points in each element, defining a<br>C### grid point for each unique gauss point (as gauss points on<br>C### the boundary should only have one grid point, though they<br>C### are shared between two elements. <br>C### <br>C### After this, defines grid points to use for calculating<br>C### no-flux boundary conditions at grid points on the external<br>C### boundary of the mesh.<br>C### <br>C### Now also stores values of dx/dxi and dnu/dx for each gp in<br>C### DXQ to be used later in the solution process. Coordinate<br>C### position (in rectangular cartesian) is now stored in XQ,<br>C### including fibre angle and sheet angle.<br></pre> </dd></dl>
<h4>Embedded HTML Tags</h4>
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).
<p>
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:
</p><dl><dd> <pre>C#### Description:<br>C### <HTML><br>C### MESH3_NB(i,j) are the basis numbers used in the mesh.<br>C### When j=1 the bases are BE bases. When j=2 the bases<br>C### are FE bases.<br>C### <UL><br>C### <LI>i=1 gives the main basis function number <br>C### <LI>i=2 gives the bottom sector (apex node 1) basis number<br>C### <LI>i=3 gives the top sector (apex node 3) basis number<br>C### </UL><br>C### </HTML><br></pre> </dd></dl>
<p> </p><hr> <p>
</p><p>
</p><h3>Groups</h3>
<p>
A <b>Group</b> 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.
</p><p>
</p><hr>
<p>
</p><h3>Specific Groups</h3>
<p>
There are currently six groups defined for use in the CMISS source: </p><ul><li>Module </li><li>Subroutine </li><li>Function </li><li>Command </li><li>Variable </li><li>Comment </li><li>Block Data </li></ul>
<p>
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.
</p><h4>Module Group</h4>
The head tag of the module group is <b>Module</b> and the group must have one <b>Description</b> tag as well as an optional <b>See-Also</b> tag.
<dl><dt>Tags: </dt><dd><b>Module</b> - The name of the module, such as "FE10",
or "FEUSER"
</dd><dd><b>Description</b> - A description of the module. </dd><dd><b>See-Also</b> - 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.
- </dd><dd><b>Routine</b> - 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.
</dd></dl>
For example: <dl><dd> <pre>C#### Module: FE07<br>C### Description: Routines to solve fem and bem equations<br>C### Routine: GETEIGENWORK Allocates the eigenproblem work arrays<br>C### Routine: SOLVE_SYSTEM Solves a linear system of equations<br></pre> </dd></dl>
<h4>Subroutine Group</h4>
The head tag of the subroutines group is <b>Subroutine</b> and the group must have one <b>Description</b> tag. Like the Module group above, the Subroutine Group may also have an optional <b>See-Also</b> tag.
<dl><dt>Tags: </dt><dd><b>Subroutine</b> - The name of the subroutine, such as
"BASIS8" or "GINOUT"
</dd><dd><b>Description</b> - A description of the subroutine. </dd><dd><b>See-Also</b> - A list of comma seperated names of
other relavant information.
- </dd><dd><b>See-Example</b> - A list of comma seperated names of
- relavant examples.
</dd></dl>
For example: <dl><dd> <pre>C#### Subroutine: BASIS8 <br>C### Description:<br>C### BASIS8 supplements basis function array<br>C### PG(ns,nu,ng,nb),ns=1,.NST(nb), with auxiliary<br>C### functions ns=NST(nb) + na, where na=1,..NAT(nb), for use<br>C### with element parameters<br>C### ZA(na,nc,nh,ne). <br></pre> </dd></dl>
<h4>Function Group</h4>
The head tag of the function group is <b>Function</b>, and the group must also include a <b>Description</b> tag. There are also four optional tags: <b>Type</b>, <b>See-Also</b> and <b>Returns</b>.
<dl><dt>Tags: </dt><dd><b>Function</b> - The name of the function, such as
"FHN_ION" or "NULL"
</dd><dd><b>Description</b> - A description of the function. </dd><dd><b>Type</b> - The type of the return data of the
function.
- </dd><dd><b>See-Also</b> - A list of comma seperated names of
- other relavant information.
</dd></dl>
<dl><dd> <pre>C#### Function: CHMESH_FX<br>C### Type: REAL*8<br>C### Description:<br>C### CHMESH_FX is one of J Crocombe's (temporary) change <br>C### mesh functions.<br></pre> </dd></dl>
<h4>Command Group</h4>
The command group's head tag is <b>Command</b>. It has a <b>Description</b> tag and an optional <b>See-Also</b> tag. In addition there can be one or more <b>Parameter</b> tags for each of the commands paramters.
<dl><dt>Tags: </dt><dd><b>Command</b> - The name of the command, such as
"show reactions" or "export nodes"
</dd><dd><b>Description</b> - A description of the command. </dd><dd><b>See-Also</b> - A list of comma seperated names of
other relavant information.
- </dd><dd><b>Parameters</b> - 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.
</dd></dl>
Examples:
<dl><dd> <pre>C#### Command: define data;m <br>C### Parameter: <geometry/fibre/field/sheet>geometry<br>C### What sort of data to define.<br>C### Parameter: <on WSS>1<br>C### Which workstation (window) to display the information.<br>C### Description:<br>C### The same information as above can be entered using<br>C### the mouse. The mouse is used to locate the positions<br>C### of the data, and the value at the location is<br>C### entered via the keyboard.<br></pre> </dd></dl>
<h4>Variable Group</h4>
The variable group's head tag is <b>Variable</b> and it must also contain a <b>Description</b> tag. Optional tags for this group are <b>Type</b>, <b>Set-Up</b> and <b>See-Also</b>.
<dl><dt>Tags: </dt><dd><b>Variable</b> - The name of the variable, such as
"EDD" or "NJ_FIT"
</dd><dd><b>Description</b> - A description of the variable. </dd><dd><b>See-Also</b> - A list of comma seperated names of
other relavant information.
- </dd><dd><b>Type</b> - The type of the variable, whether it be
- INTEGER or REAL*8.
- </dd><dd><b>Set-Up</b> - The routine in which the variable is
- set up.
</dd></dl>
Examples:
<dl><dd> <pre>C#### Variable: ITYP10(nr)<br>C### Type: INTEGER<br>C### Set_up: IPCOOR<br>C### Description:<br>C### ITYP10(nr) is 1..5 for coordinates rectangular<br>C### cartesian/cylindrical polar/spherical polar/prolate<br>C### spheroidal/oblate spheroidal.<br></pre> </dd></dl>
<h4>Comment Group</h4>
Comments are groups of information that don't appear elsewhere, and generally describe some over all philosophy or structure within the code.
<dl><dt>Tags: </dt><dd><b>Comment</b> - The title of the comment, such as
"SPARSITY STRUCTURES" or "BINARY FILE FORMAT"
</dd><dd><b>Description</b> - The descriptive text. </dd><dd><b>See-Also</b> - A list of comma seperated names of
other relavant information.
</dd></dl>
Examples:
<dl><dd> <pre>C#### Comment: FIBRE IMBRICATION and SHEET ANGLES<br>C### Description:<br>C### Eqtn 5 of "Laminar Structure of the Heart" by Le<br>C### Grice, Hunter and Smaill defines how the fibre<br>C### reference vectors F_VECTOR, G_VECTOR and H_VECTOR<br>C### are computed from the microstructural material<br>C### axis vectors A_VECTOR, B_VECTOR and C_VECTOR.<br>C### Three successive coordinate rotations define the<br>C### transformation (the order IS important). Firstly,<br>C### the material vectors are rotated by GAMA-PI/2<br>C### about the fibre axis until the new sheet axis lies<br>C### in the Xi1-Xi2 plane. Secondly, the resulting<br>C### vectors are rotated by BETA about the new sheet<br>C### axis until the new fibre axis also lies in the<br>C### Xi1-Xi2 plane. Lastly, the resulting vectors are<br>C### rotated by ALFA about the new sheet-normal axis<br>C### (which now coincides with the Xi1-Xi2 plane<br>C### normal) until the new fibre axis coincides with<br>C### the Xi1 base vector. <br></pre> </dd></dl>
<h4>Block Data Group</h4>
The head tag of the block data group is <b>BlockData</b> and the group must have one <b>Description</b> tag.
<dl><dt>Tags: </dt><dd><b>BlockData</b> - The name of the block data. </dd><dd><b>Description</b> - A description of the block data. </dd></dl>
Examples:
<dl><dd> <pre>C#### BlockData: BLK30<br>C### Description:<br>C### BLK30 sets up parameter titles in common block<br></pre> </dd></dl>
<hr>
<h3>Appendix A: Comment Rule File</h3>
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.
<pre>--<br>-- Rules for parsing the embedded comments within conforming files<br>-- (such as the CMISS FORTRAN source, etc)<br>--<br><br><br>-- Definition of CMISS comments -----------------------------------------------<br>--<br><br>define MODULE as<br> <<br> HEAD Module<br> TAG Description<br> TAG Routine0..1 -- Optional<br> TAG See-Also0..1 -- Optional<br> ><br><br><br>define SUBROUTINE as<br> <<br> HEAD Subroutine<br> TAG Description<br> TAG See-Also0..1 -- See-Also is an optional element<br> TAG See-Example0..1 -- See-Example is an optional element<br> ><br><br><br>define FUNCTION as<br> <<br> HEAD Function<br> TAG Description<br> TAG Type0..1 -- Optional<br> TAG Returns0..1 -- Optional<br> TAG See-Also0..1 -- Optional<br> ><br><br><br>define COMMAND as<br> <<br> HEAD Command<br> TAG Description<br> TAG Parameter0..N -- There can be zero, one, or more parameters<br> TAG See-Also0..1 -- Optional<br> ><br><br><br>define VARIABLE as<br> <<br> HEAD Variable<br> TAG Description<br> TAG Type0..1 -- Optional<br> TAG Set-Up0..1 -- Where var is first set up (Optional)<br> TAG See-Also0..1 -- Optional<br> ><br><br><br>define COMMENT as<br> <<br> HEAD Comment<br> TAG Description<br> TAG See-Also0..1 -- Optional<br> ><br><br><br>define BlockData as<br> <<br> HEAD BlockData<br> TAG Description<br> ><br></pre>
<p> </p><hr> <p>
</p><h3>Further Examples</h3>
<pre>C#### Variable: JTYP14<br>C### Type: INTEGER<br>C### Set_up: IPMESH<br>C### Description:<br>C### <HTML><br>C### JTYP14 is mesh type for specialized meshes (1 = regular fractal<br>C### tree; 2 = stochastic fractal tree) as follows:<br>C### Fractal tree branch parameters:<br>C### <UL><br>C### <LI>Ratio_Angle,Ratio_Length,Ratio_Diameter<br>C### <LI>B_angle_y(no_gen) : mean angle branch makes with y-axis<br>C### <LI>B_angle_xy(no_gen): mean angle branch makes with xy-plane<br>C### <LI>B_angle_SD(no_gen): standard deviation of angles<BR><br>C### Note: angles are generated with Normal distribution using mean <br>C### and standard deviation obtained by dividing previous generation<br>C### values by Ratio_Angle.<BR><br>C### <LI>B_length(no_gen)<br>C### <LI>B_diameter(no_gen)<br>C### <LI>B_volume(no_gen)<br>C### <LI>B_flow(no_gen) ?? <-- not needed<br>C### <LI>NW(ne,1)=generation number<br>C### </UL> <br>C### </HTML><br></pre>
<pre>C#### Subroutine: IPGRID<br>C### Description:<br>C### IPGRID defines collocation grids na=1,NMGT (NMGT>1 for <br>C### multigrid if ITYP4(nr,nx)=4). Steps through all elements, then <br>C### through all gauss points in each element, defining a grid point <br>C### for each unique gauss point (as gauss points on the boundary <br>C### should only have one grid point, though they are shared between <br>C### two elements. After this, defines grid points to use for <br>C### calculating no-flux boundary conditions at grid points on the <br>C### external boundary of the mesh. Now also stores values of <br>C### dx/dxi and dnu/dx for each gp in DXQ to be used later in the <br>C### solution process. Coordinate position (in rectangular <br>C### cartesian) is now stored in XQ, including fibre angle and<br>C### sheet angle.<br>C### See-Also: ITYP4, XQ<br></pre>