View source for NOTES

You can annotate ASCEND [[MODEL|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:

<source lang="a4c">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;</source>

Note that in this case the <tt>SELF</tt> 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.

<source lang="a4c">height &quot;distance above ground-level&quot; IS_A distance;</source>

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

<source lang="a4c">height "distance above ground-level"
, length
, width "distance between left and right faces"
    IS_A distance;</source>

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:

<source lang="a4c">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;</source>

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 &rarr; 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 ==

There is some further information in the [[:Category:Documentation|ASCEND Manual]].

[[Category:Documentation]]
[[Category:Syntax]]