NOTES

You can annotate ASCEND MODELs with various information that aids understanding for the end user, or provides information to the solver (Solver NOTES). In general, this is a system of attaching meta-data to your model, for whatever purpose you can imagine.

Notes are stored in a temporary database in memory. Each note has the following attributes:

• model: the type (MODEL) to which the model relates
• category: a short string describing the purpose of the note.
• object: the variable (IS_A) that the note refers to, or SELF if the note refers to the MODEL as a whole.
• content: a (possibly quite long) string with the actual text of the note.

NOTES

If you are inside a MODEL statement, you can declare notes all together, as a block:

MODEL mymodel;
  NOTES
    'author' SELF {Art Westerberg}
    'creation date' SELF {18 Jan 2008}
    'description' height {Distance above ground level}
    'description' submodel.x {This value is derived from mymodel.height!}
  END NOTES;

  height IS_A distance;
  submodel IS_A my_other_model(height);
  (* etc... *)
END mymodel;

Note that in this case the SELF keyword attaches the notes to the type 'mymodel', instead of to a particular variable, and the notes' MODEL is automatically set, in this case to 'mymodel'.

Note that the object for the note can be 'SELF' (no quotes), or a local variable name (eg 'height'), or a variable defined in a sub-model (eg 'submodel.x').

Inline notes

You can annotate a variable using a double-quoted string inside your IS_A statement.

height "distance above ground-level" IS_A distance;

Multiple variables can also be declared at a time, each with their own (optional) annotation:

height "distance above ground-level"
, length
, width "distance between left and right faces"
    IS_A distance;

When notes are declared in this way, it is identical to a NOTE declared with the category name 'inline'.

ADD NOTES

You can declare notes for a particular MODEL later on, even in a different file, if you want. In this case, the syntax is as follows:

ADD NOTES IN mymodel;
    'description' SELF {This model does some really difficult analysis that even I don't understand}
    'author' SELF {John Pye}
    'source' height {Data for this variable comes from direct measurement of the apparatus}
    'source' submodel.x {This is a calculated value}
END NOTES;

As before, the notes can either be made to apply to the model as a whole (using SELF), or to individual variables, or even to variables in submodels of the model named in your ADD NOTES IN statement.

Accessing NOTES

Notes can be accessed via a special window in the Tcl/Tk GUI, and there are searching facilities there.

In the PyGTK GUI, NOTES for a particular model can be read by first clicking on a model, then selecting View → Show notes.

NOTES for other purposes

Notes can be used to pass parameters to the solver. See Solver NOTES.

It has also been imagined that NOTES could be quite useful for containing metadata that would allow a graphical flowsheet. to be constructed for a particular model, for example by encoding a graphically form for a MODEL that allows it to be drawn onto a flowsheet, or encoding information about which variables are 'inputs' and which are 'outputs'.

Support for these types of notes will required new functionality to be implemented in the GUI.

See also

• Comments
• further information on NOTES in the ASCEND Manual.