History for Source documentation format
changed:
-
<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 Routine[0..1] -- Optional<br> TAG See-Also[0..1] -- Optional<br> ><br><br><br>define SUBROUTINE as<br> <<br> HEAD Subroutine<br> TAG Description<br> TAG See-Also[0..1] -- See-Also is an optional element<br> TAG See-Example[0..1] -- See-Example is an optional element<br> ><br><br><br>define FUNCTION as<br> <<br> HEAD Function<br> TAG Description<br> TAG Type[0..1] -- Optional<br> TAG Returns[0..1] -- Optional<br> TAG See-Also[0..1] -- Optional<br> ><br><br><br>define COMMAND as<br> <<br> HEAD Command<br> TAG Description<br> TAG Parameter[0..N] -- There can be zero, one, or more parameters<br> TAG See-Also[0..1] -- Optional<br> ><br><br><br>define VARIABLE as<br> <<br> HEAD Variable<br> TAG Description<br> TAG Type[0..1] -- Optional<br> TAG Set-Up[0..1] -- Where var is first set up (Optional)<br> TAG See-Also[0..1] -- Optional<br> ><br><br><br>define COMMENT as<br> <<br> HEAD Comment<br> TAG Description<br> TAG See-Also[0..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>
Forgot your password?
New user?