ASCEND - User contributions [en]

Binary installer for Boost on MinGW

2010-05-13T14:06:14Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

Here is an installer for [http://www.boost.org/ Boost] version 1.34.1 on MinGW using NSIS:

<div style="padding-top:8px;padding-bottom:12px"><div style="border:solid 2pt gray;background-color:#ffff88;margin-top:0px;margin-bottom:5px;padding:3px;width:35em">
* <a href="/images/6/60/Boost-1.41.0-mingw.exe" class="internal" title="Boost-1.41.0-mingw.exe">boost-1.41.0-mingw.exe</a> (binary installer, static libraries, 5.0 MB)
* <a href="/images/0/0a/Boost-1.34.1-mingw.exe" class="internal" title="Boost-1.34.1-mingw.exe">boost-1.34.1-mingw.exe</a> (binary installer, shared libraries, 3.4 MB)</div></div>

I have been able to build a couple of different projects against these Boost libraries, specifically ones that use the Boost Serialization components, but I couldn't consider it to have been extensively tested. Please [[User:Jpye|let me know]] if you have any problems.

[[Image:boost-installer.png]]

== Instructions for building Boost-1.41.0 on MinGW ==

''This page is currently being updated below...''

* make sure you have ~3G of spare space on your machine before starting this process -- building Boost takes '''lots''' of space.
* download the 3.1.17-ntx86 version of bjam from [http://sourceforge.net/projects/boost/files/boost-jam/3.1.17 here]
* unpack that zip file and, using MSYS, <tt>cp bjam.exe /mingw/bin</tt>.
* download and unpack the .tar.bz2 version of the 1.41.0 release of boost from [http://sourceforge.net/projects/boost/files/boost/1.41.0 here]
* enter the boost_1_41_0 directory via MSYS
* <tt>bjam --build-dir=boost-build --toolset=gcc --build-type=complete stage release</tt>
* Go and make yourself several cups of tea
* <tt>bjam --build-dir=boost-build --toolset=gcc install</tt>

To create the binary package, unpack <a href="/images/5/50/Boost-mingw-scripts.tar.bz2" class="internal" title="Boost-mingw-scripts.tar.bz2">boost-mingw-scripts.tar.bz2</a>, enter the boost-mingw-scripts directory, and run <tt>scons</tt>. You will need to have SCons, Python and NSIS installed on your system. You may need to make some minor changes at the top of the SConstruct file first. Packaging takes a few minutes, owing to the ~5000 header files present in Boost.

The resulting binary installation of Boost will contain only the static libraries for Boost, enabling you to easily distribute any binaries that you link against it.

'''Note:''' this page has been protected from non-admin edits, to prevent other people uploading files. You can make comments via the 'discussion' page if you wish, though.

[[Category:Miscellany]]
[[Category:MinGW]]

Faxing via Google Voice

2010-05-13T14:06:04Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

== My goal ==

My goal was to configure Google Voice and my fax machine (an HP C6150 All In One (printer, fax, scanner, copier)) so I could fax via Google Voice. If that would work, then I could fax at very low cost virtually anywhere in the world.

== What is Google Voice ==

I just signed up for Google Voice (one has to be invited, but one can sign up to be invited, which I did some time ago and got invited a few days ago). With this service, Google gives someone in the USA a single phone number that, when called, will ring any or all of the phones that person owns. One can choose to answer a call, send it directly to voice mail, listen in to the voice mail and possible accept it then, or answer and record it. There are many other very interesting and useful features you can find by going to the [http://www.google.com/googlevoice/about.html * Google Voice homepage]. One can also place calls from any of these phones by calling the Google Voice number. Google then calls one back. After answering, dialing 2 allows one to dial another phone anywhere in the world. For calls originating in the US, one can call many places around the world for about the same costs as using SKYPE. DO NOT USE THIS CAPABILITY OUTSIDE THE USA, HOWEVER. The callback from Google to you incurs roaming charges.

== The needed insights ==

Here are the two bits of information that one needs to make this happen.

(1) The C6150 allows one to enter a telephone number containing one second long dialing delays. One has to search to find how, but including a dash (-) inserts a one second delay in dialing. The dash is hidden under the asterisk (*) button, which one reaches by pressing * twice.

(2) One can set up a phone under Settings on one's <a href="https://www.google.com/voice/" class="external text" title="https://www.google.com/voice/" rel="nofollow">* Google Voice account</a> to go directly to voicemail without one having to answer the return call from Google Voice. That is the default setting for mobile phones but not for a home phone (and, of course, my fax is tied through my home phone). And further, one is given the option when going into voicemail to dial a phone number by entering a 2 and then the number.

== How to make it work ==

So here is the way to make it all work ---

1. Go to your Google Voice account, select Settings, Phones and then the Edit option for the phone on which you have your fax machine residing. Open the "Show Advanced Settings."
Then select "Yes" and "PIN not required (for added convenience)" for the "Direct access to voicemail when calling your Google number from this phone?" You could of course have the PIN required, but then you need to add that to the phone number you construct below. I figured my home phone is safe from someone misusing it.

2. Send your fax but construct the fax recipient's number as follows

<pre> YourGoogleVoiceNumber--2--NumberOfFaxReceivingMachine (those are dashes in this number to insert 2 two second pauses).
</pre>

For example, if your Google Voice number is 515-555-5565 and the fax machine is at +44-55-56-57-58-59, then set up the number to be

<pre>15155555565--2--011445556575859
</pre>

Note this would send a fax overseas and that the 011 replaces the plus sign (I think using a plus sign would also work but did not try it).

[[Category:Miscellany]]

Porting to Mac/gtk-mac-bundler

2010-05-13T14:05:55Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

[[Porting_to_Mac|← Porting to Mac]]

This page contains some notes on how [http://sourceforge.net/apps/trac/gtk-osx/wiki/Bundle ige-mac-bundler] (and maybe other tools) do the job of making portable, self-contained GTK+ applications work on Mac. The notes were prepared during the course of porting [[ASCEND_overview|ASCEND]] to Mac. Please feel free to set me straight on any wrong observations, missing information, etc.

The following observations come from bundling up GtkDemo using ige-mac-bundler.

== GTK libraries ==
GTK libraries are copied into the Contents/Resources/lib directory in the application bundle. Their 'install names' are changed so that they look like:

<pre>
$ otool -L libgtk-quartz-2.0.0.dylib
libgtk-quartz-2.0.0.dylib:
/Users/john/gtk/inst/lib/libgtk-quartz-2.0.0.dylib (compatibility version 1801.0.0, current version 1801.2.0)
@executable_path/../Resources/lib/libgdk_pixbuf-2.0.0.dylib (compatibility version 1801.0.0, current version 1801.2.0)
@executable_path/../Resources/lib/libgdk-quartz-2.0.0.dylib (compatibility version 1801.0.0, current version 1801.2.0)
@executable_path/../Resources/lib/libpangocairo-1.0.0.dylib (compatibility version 2401.0.0, current version 2401.5.0)
</pre>

For the GtkDemo app, the following libraries are copied:

<pre>
$ ls
charset.alias libfreetype.6.dylib libgobject-2.0.0.dylib libpangoft2-1.0.0.dylib
gtk-2.0 libgdk-quartz-2.0.0.dylib libgtk-quartz-2.0.0.dylib libpixman-1.0.dylib
libatk-1.0.0.dylib libgdk_pixbuf-2.0.0.dylib libintl.8.dylib libpng12.0.dylib
libcairo.2.dylib libgio-2.0.0.dylib libjpeg.7.dylib libtiff.3.dylib
libexpat.1.dylib libglib-2.0.0.dylib libpango-1.0.0.dylib
libfontconfig.1.dylib libgmodule-2.0.0.dylib libpangocairo-1.0.0.dylib
</pre>

== Pixbuf loaders ==

The environment variable GDK_PIXBUF_MODULE_FILE is used to specify the path to a file usually named <tt>gdk-pixbuf.loaders</tt>. This file contains a list of shared libraries that perform the task of loading various kinds of images into GTK+.

This <tt>gdk-pixbuf.loaders</tt> file can be automatically generated by the script <tt>~/gtk/inst/bin/gdk-pixbuf-query-loaders</tt>.

This contents of <tt>gdk-pixbuf.loaders</tt> are automatically edited by <tt>ige-mac-bundler</tt> to replace the absolute file paths with paths like <tt>@executable_path/../Resources/lib/gtk-2.0/loaders/libpixbufloader-png.so</tt>, etc.

The pixbuf loaders are copied into the locally-consistent location <tt>Contents/Resources/lib/gtk-2.0/2.xx.xx/loaders</tt>, where xx.xx is the particular GTK+ version being used.

== Icons and themes ==

Icons and themes are copied into <tt>Contents/Resources/share</tt>. I got the following files:

<pre>$ ls -R
icons themes

./icons:
hicolor

./icons/hicolor:
index.theme

./themes:
Default Emacs Raleigh

./themes/Default:
gtk-2.0-key

./themes/Default/gtk-2.0-key:
gtkrc

./themes/Emacs:
gtk-2.0-key

./themes/Emacs/gtk-2.0-key:
gtkrc

./themes/Raleigh:
gtk-2.0

./themes/Raleigh/gtk-2.0:
gtkrc
</pre>

Didn't see any sign of actual image or icon files anywhere... perhaps the default ones are embedded in the shared library somehow.

== Pango configuration files ==

In <tt>Contents/Resources/etc/pango/pangorc</tt> the following text was found:

<pre>
$ cat pangorc
[Pango]
ModuleFiles=./pango.modules
</pre>

The file <tt>pango.modules</tt> is present in the same directory, but is empty.

== GTK configuration files ==

In <tt>Contents/Resources/etc/gtk-2.0/gtkrc</tt> the following text was found:

<pre>
$ cat gtkrc
gtk-icon-theme-name = "Tango"
gtk-enable-mnemonics = 0
</pre>

In same directory, there is another empty file called <tt>gtk.immodules</tt>.

== Use of install_name_tool ==

In <tt>ige-mac-bundler</tt>, all DYLD paths have been set relative to the @executable_path. The executable is kept inside the bundle as <tt>Contents/MacOS/GtkDemo-bin</tt>. This means, for example, that <tt>@executable_path/../Resources/lib</tt> takes the loader to folder containing all the GTK shared libraries.

'''Note''': for the case of PyGTK bundles, assuming Apple Python or MacPython are being used but not being included in the bundle, we can't pull this trick, because the @executable_path would then be outside the application bundle, and no help for locating GTK libraries. An alternative approach might be possible using @rpath set on the PyGTK shared libraries, and this needs to be tried out.

== Environment variables ==

The file <tt>Contents/MacOS/GtkDemo</tt> is the entry-point for the application (as directed by <tt>Info.plist</tt>) and is a shell-script that sets various required environment variables so that GTK can find all its stuff:

'''NOTE''': in the following, the "`pwd`/$0" causes problems if you invoke the <tt>ige-mac-bundler</tt>-bundled from the command line from any directory other than <tt>Contents/MacOS</tt>. I think that this is a bug.

<source lang="a4c">name="`basename $0`"
tmp="`pwd`/$0"

tmp=`dirname "$tmp"`
tmp=`dirname "$tmp"`
bundle=`dirname "$tmp"`

bundle_contents="$bundle"/Contents
bundle_res="$bundle_contents"/Resources
bundle_lib="$bundle_res"/lib
bundle_bin="$bundle_res"/bin
bundle_data="$bundle_res"/share
bundle_etc="$bundle_res"/etc

export DYLD_LIBRARY_PATH="$bundle_lib"
export XDG_CONFIG_DIRS="$bundle_etc"/xdg
export XDG_DATA_DIRS="$bundle_data"

export GTK_DATA_PREFIX="$bundle_res"
export GTK_EXE_PREFIX="$bundle_res"
export GTK_PATH="$bundle_res"

export GTK2_RC_FILES="$bundle_etc/gtk-2.0/gtkrc"
export GTK_IM_MODULE_FILE="$bundle_etc/gtk-2.0/gtk.immodules"
export GDK_PIXBUF_MODULE_FILE="$bundle_etc/gtk-2.0/gdk-pixbuf.loaders"

export PANGO_RC_FILE="$bundle_etc/pango/pangorc"</source>

After the above, there is some locale-related stuff (see [http://github.com/jralls/ige-mac-bundler/blob/master/bundler/launcher.sh launcher.sh] for the details.

Next the script does something with charset alias ('''FIXME''' what's this doing?):

<source lang="a4c">if test -f "$bundle_lib/charset.alias"; then
export CHARSETALIASDIR="$bundle_lib"

fi</source>

Next, a variable EXTRA_ARGS is initialised empty and an optional <tt>environment.sh</tt> is run, allowing command-line arguments to be appended to EXTRA_ARGS, or just to set additional application-specific or user-specific environment variables.

Then, the script throws out some Mac-related command-line parameters that are useless to GTK:

<source lang="a4c"># Strip out the argument added by the OS.
if [ x`echo "x$1" | sed -e "s/^x-psn_.*//"` == x ]; then

shift 1
fi</source>

Finally, the script launches the executable.

<source lang="a4c">$EXEC "$bundle_contents/MacOS/$name-bin" $* $EXTRA_ARGS</source>

PyGTK Screenshots

2010-05-13T14:05:45Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

There are two user interfaces for ASCEND. The older, more mature user interface (and the only one offered in the 'stable' 2000 release) is the [[TcltkScreenshots|Tcl/Tk GUI]], for which [[TcltkScreenshots|screenshots]] are not shown here. This page shows the newer Python/PyGTK GUI that has been under development more recently by [[User:Jpye|John Pye]] For instructions on getting it running, see the [[PythonWrapper]] page.

== Browser ==

This is the main instance browser in the PyGTK ASCEND GUI. Fixed <tt>solver_var</tt>s are shown in green, free ones are shown in blue, all other instances/variables are shown in black. Values of all of these can be edited directly in-place. Errors and messages are shown in the lower pane, methods can be run from the combobox at the top.

[[Image:ascend-browser.png]]

The ASCEND GUI is different from the [[TcltkScreenshots|Tcl/Tk GUI]] in that it concentrates the user interface into a single window as far as possible, to make ASCEND more 'approachable' for new users. Solver selection and parameter control is the via menus. The 'Library' concept is mostly bypassed, as models loaded from the shell (for example by typing <tt>ascend mymodel.a4c</tt>) are immediately opened, and, if they contain a 'self-titled' <tt>MODEL</tt> declaration (eg <tt>MODEL mymodel REFINES mybasetype</tt>), then that model is instantiated and its <tt>on_load</tt> method is run. The 'Modules' allows types to be selected from any of the loaded modules, but often now it is not needed. It is also automatically emptied when the user requests to instantiate load a new module; there is no way of having multiple models at a time.

'''Note''': the above is running on Linux (Fedora Core 4) but being viewed on Windows 2000 via [http://wiki.freedesktop.org/wiki/Xming Xming].

== Plotting with PyGTK GUI ==

To plot from the PyGTK GUI, you must set up your model according to Chapter 4 of the <a href="/images/6/61/Book.pdf" class="internal" title="Book.pdf">User's Manual (1 MB .pdf)</a>. Then, you can right-click on an instance of <tt>plt_plot_integer</tt> or <tt>plt_plot_symbol</tt> and click 'Plot' and your plot should appear in a new window.

[[Image:plot-right-click.png]]

Plotting under PyGTK is done with the [http://matplotlib.sourceforge.net/ matplotlib] library, which gives the additional benefit of allowing plots to be easily exported in a variety of formats including SVG and EPS, PNG and JPEG, etc.

You can also produce thiese plots programmatically using the [[PythonWrapper]] as follows:

<pre>instance.getPlot().show()
</pre>

Most of the functionality that extracts the plot data from the ASCEND instance hierarchy in provided through the SWIG interface, allowing other scripting languages to access the raw plot data.

Here is a screenshot of a the 'plotbvp' demo from the ASCEND standard models:

[[Image:ascend-pygtk-plot.png]]

== Editing solver parameters ==

Recently we've added support for editing solver parameters through the PyGTK GUI. Any parameter that you've changed shows in yellow until you click 'apply'. Note that your parameters aren't saved: if you reload your model they will be reset to their default values. Unfortunately.

[[Image:solver-params-2.png]]

== Viewing an incidence matrix ==

This is a simple overall view of the sparsity matrix for a system, either before or after you've solved it. It permits zooming and exporting of the image to various output formats, which should be useful in some case. Mouse-ing over the matrix will show you the variable and relation you're looking at, via the text in the bottom-right of the window (see also the 'Diagnose' feature below). Fixed variables are shown in green, solved free variables are shown in black. We haven't checked out how this stuff works for conditional modelling cases just yet.

[[Image:ascend-sparsity.png]]
<div class="thumb tnone"><div class="thumbinner" style="width:302px;">[[Image:Sparsity-4bar.png]] <div class="thumbcaption"><div class="magnify">[[File:Sparsity-4bar.png|<img src="/skins/common/images/magnify-clip.png" width="15" height="11" alt="" />]]</div>A smaller incidence matrix showing mouse-over variable info in bottom right</div></div></div>

== Observers ==

Here is a screenshot of the [[Observers|observer]] functionality, which is roughly equivalent to the 'PROBE' in the [[TcltkScreenshots|Tcl/Tk GUI]]. In the 'simulation' window you can set which solver variables you want to observe (right click, select 'Observe') and they will appear in your Observer tab.

[[Image:ascend-observer2.png]]

Each time you have solved a scenario that you want to keep, press ctrl-K to '''keep''' the current observed values in the observer data window.

Note that the bold row in the table is 'live'; its values will ''follow'' your current simulation, and it is '''is editable'''. Edit any bold entry in the table, and so long as it corresponds to a FIXED variable, the results will show up immediately in the other columns (assuming you have set 'Auto' on).

When you have run all the scenarios you want, hit 'ctrl-C' and you can copy your scenario data to another application. You can see here that the results paste into OpenOffice spreadsheets in an immediately useful form:

[[Image:ascend-paste.png]]

The Observer tab is also used, in slighly adapted form, as the method in which integration results (time series) are viewed.

You can also plot from the [[Observers|observer tab]]. Just click the 'plot' button and the second column will be plotted against the first column.

<div class="thumb tnone"><div class="thumbinner" style="width:402px;">[[Image:Observer-plots.png]] <div class="thumbcaption"><div class="magnify">[[File:Observer-plots.png|<img src="/skins/common/images/magnify-clip.png" width="15" height="11" alt="" />]]</div></div></div></div>

== Manipulating variable properties ==

You can set upper and lower bounds and scaling values for variables via the Properties command. Effort has been made to ensure it can be very easily navigated using the keyboard: F4 opens the variable properties windows, Tab between fields, Enter to confirm, Escape to cancel. If you omit to enter any units, the 'preferred' units will be assumed. If you enter a value in incompatible units, the edit box will show red and you will have to correct it or else click 'cancel'.

[[Image:variable-properties.png]]

== Viewing Relations and residuals ==

The same 'F4' shortcut can be used to review the definitions of relation instances:

[[Image:relation-properties.png]]
'''Note''': the above is running on FC4 but being viewed on Windows 2000 via [http://wiki.freedesktop.org/wiki/Xming Xming].

== 'Block Diagnose' feature ==

This is a new idea for examining the non-converging block or blocks in your model. After you have attempted to solve your model, this screen can be used to look at the structure of the block which is causing trouble, and directly examine the equations and variables that are involved. Below is a preview of this feature:

[[Image:block-diagnose-4.png]]

In the above, it is intended that

* values at or near their bounds should be red
* large-valued variables should be coloured in bright pink,
* largish values in orange
* values near nominal in green
* smallish values in pale blue
* very small values in bright blue

Probably we'll find that different colouring schemes are suitable for different occasions. For example, finding equations with large residuals would use colouring by residual magnitude. Perhaps colouring by magnitude of elements in the jacobian would be useful as well. Would appreciate comments on this.

We plan to add a '''graph''' view to this window as well, which would show the actual connection between variables and relations, so that the evaluation 'loops' would be more clearly identifiable.

== Solver status popup ==

You can follow the solver's progress using the 'Solver Status' popup, It reports the number of variables that have been solved, the size of the current block, the current RMS residuals, elapsed time, total iterations and iterations in the current block.

[[Image:solverstatus.png]]

The popup can also be used to interrupt the solver. It can be set to close automatically once the solver has completed (via the Tools menu). We plan to add similar functionality to the 'Diagnose' window so that step-by-step solving can be performed from there as well.

<br />

== Running under Windows ==

The PyGTK GUI for ASCEND runs under Windows as well. This version was compiled using MinGW and run using Python 2.5 for Windows plus the Windows port of GTK+, and a couple of other python-related libraries.

[[Image:windows-ascend.png]]

== Editing with TextPad on Windows ==

[http://www.textpad.com/ TextPad] is a popular text editor for Windows. You can use our {{src|tools/textpad/ascend.syn}} file to give you syntax-highlighting of code when using that editor.

[[Image:textpad-ascend.png]]

== Integrator (dynamic simulation) ==

Here is the new Integrator window in the PyGTK GUI. It supports the LSODE and IDA integrators, although the latter is still being developed. Support for setting the solution tolerance needs to be added, as well as possibly alternative methods for specifying the integration timesteps. Timesteps aren't currently 'units aware', either.

[[Image:integrator-gui.png]]

Here is the progress dialog:

[[Image:integrator-progress.png]]

== Launching ASCEND from Gedit ==

We provide syntax highlighting to for the ''gedit'' edit on GNOME (Ubuntu, Fedora, etc). Note also the [[PyGTK GUI command-line parameters]], which can be of use when integrating with gedit. In current versions of Fedora and Ubuntu, the {{srcdir|tools/gtksourceview-2.0/}} of our gedit syntax highlighting must be used. Otherwise, use the {{srcdir|tools/gedit/}}.

[[Image:ascend-from-gedit.png]]

== Plotting from external Python methods ==

The [[ExtPy]] module allows general scripts to be run from inside ASCEND <tt>METHODS</tt>. Using the [[PythonWrapper]] you can then do anything you like with the ASCEND engine, such as running a model with a range of parameters and plotting the output, as with this simple four-bar linkage example (See [http://ascendserver.cheme.cmu.edu/svn/ascend/code/trunk/models/johnpye/fourbar.a4c fourbar.a4c] and [http://ascendserver.cheme.cmu.edu/svn/ascend/code/trunk/models/johnpye/fourbarplot.py fourbarplot.py]).

<div class="thumb tnone"><div class="thumbinner" style="width:402px;">[[Image:Fourbar.png]] <div class="thumbcaption"><div class="magnify">[[File:Fourbar.png|<img src="/skins/common/images/magnify-clip.png" width="15" height="11" alt="" />]]</div>A four-bar linkage. The angle of the left member was swept through a range of values and the position of the mechanism plotted for each.</div></div></div>

Another example is using a [[ExtPy]] script to perform a plot of the roots of a dynamic system

<div class="thumb tnone"><div class="thumbinner" style="width:402px;">[[Image:Rootsplot.png]] <div class="thumbcaption"><div class="magnify">[[File:Rootsplot.png|<img src="/skins/common/images/magnify-clip.png" width="15" height="11" alt="" />]]</div>Roots of a system of differential-algebraic equations</div></div></div>

== IPython console ==

See [[Python console support]] for details.

<div class="thumb tnone"><div class="thumbinner" style="width:402px;">[[Image:Ipython-embed.png]] <div class="thumbcaption"><div class="magnify">[[File:Ipython-embed.png|<img src="/skins/common/images/magnify-clip.png" width="15" height="11" alt="" />]]</div>A short IPython console session within the PyGTK GUI</div></div></div>

== Units of measurement ==

You can set the preferred [[Units of measurement]] for a variable using a popup window:

<div class="thumb tnone"><div class="thumbinner" style="width:402px;">[[Image:Preferred-units.png]] <div class="thumbcaption"><div class="magnify">[[File:Preferred-units.png|<img src="/skins/common/images/magnify-clip.png" width="15" height="11" alt="" />]]</div>Setting preferred units for 'volume'</div></div></div>

== Incidence graph ==

One you have 'built' a system, you can use ASCEND to view an incidence graph that shows the sequence of calculation in a convenient form. This functionality is not currently available on Windows, only Linux at the moment. See [[Incidence Graph]] for more information.

<div class="thumb tnone"><div class="thumbinner" style="width:402px;">[[Image:Incidence-graph-reynolds.png]] <div class="thumbcaption"><div class="magnify">[[File:Incidence-graph-reynolds.png|<img src="/skins/common/images/magnify-clip.png" width="15" height="11" alt="" />]]</div>An incidence matrix for calculation of mass flow rate at specified Reynolds number</div></div></div>

[[Category:Documentation]]

Integrator API

2010-05-13T14:05:36Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

The Integrator API is the interface through which DAE and ODE solvers for [[dynamic modelling]] must communicate with ASCEND.

== Process flow ==

This section describes the process by which an Integrator is instantiated and used in ASCEND, including some detail about the associate GUI actions, outputs, and so on.

=== Registration ===

An integrator is built as an [[External_libraries|'''external''' library]] that can be either loaded automatically by ASCEND, or manually using an [[IMPORT]] statement in the user's model code.

These '''external''' libraries are loaded using 'dlopen' and then a register function is called. This function should return a data structure containing a set of function pointers, an integrator ID number, and a string integrator name, as shown:

<source lang="a4c">static const IntegratorInternals integrator_lsode_internals = {
integrator_lsode_create
,integrator_lsode_params_default
,integrator_analyse_ode
,integrator_lsode_solve
,integrator_lsode_write_matrix
,NULL /* debugfn */

,integrator_lsode_free
,INTEG_LSODE
,"LSODE"
};

extern ASC_EXPORT int lsode_register(void){

CONSOLE_DEBUG("Registering LSODE...");
return integrator_register(&integrator_lsode_internals);
}</source>

The integrator ID number is bit of a fossil; we aim to remove this ID number eventually. The integrator_register function checks that no integrator with the same name or ID has already been registered. If that's OK, the integrator is added to the list of available integrators.

=== Build ===

When the PyGTK GUI user clicks the integrate button, the system object (<tt>slv_system_t</tt>) is built if it hasn't already been built. This means that the <tt>system_build</tt> function (common with all problems, eg [[NLA|NLAs]]) is called, which in turn results in calls to <tt>analyze_make_problem</tt>. This last <tt>analyze_make_problem</tt> includes calls to <tt>analyze_make_master_lists</tt> and <tt>system_generate_diffvars</tt>.

In <tt>analyze_make_master_lists</tt> there is a 'visit' process that uses the function <tt>classify_instance</tt> to identify the following types of variables, and add them to some intermediate lists in the <tt>problem_t</tt> structure:

* variables that need to be 'observed' when integrator output is reported
* independent variables (hopefully only one, ode_type == -1)
* differential/derivative variables (ode_type >= 1)
* algebraic variables (ode_type == 0)

The function <tt>system_generate_diffvars</tt> is also called during <tt>analyze_make_problem</tt> uses a tricky sorting algorithm to arrange the diffvars into a suitable order, so that 'chains' of derivatives can be identified. These chains are split into separate ones for each variable set (eg {y, dydt, d2ydt2}), and stored in a big <tt>SolverDiffVarCollection</tt> object, which is ultimately stored in the system object (as the <tt>diffvars</tt> element).

=== Selection ===

The user must select which integrator engine they want to use to solve a problem (although a GUI can of course offer a default choice).

A list of all available (loaded) integrator enginers can be obtained with the function <tt>integrator_get_engines</tt>, which returns a list of IntegratorInternals from which all the details of the loaded integrators can be determined, including the names.

An integrator engine is selected by the user with the function <tt>integrator_set_engine</tt>, which uses the short string name for the engine as a parameter. If the integrator name exists in the engine list, integrator_free_engine is called on the previously-selected engine if necessary, then the <tt>internals</tt> field value is updated with the new IntegratorInternals pointer, and then integrator_create_engine function is called to allocate space as required.

=== Parameter and timestep input ===

Currently, integrators need some additional parameters that are not stored within the model itself. These include number of time-steps, duration of integration, etc.

During this stage, the PyGTK GUI makes a call to the function ''integrator_find_indep_var'', to determine the current value of the independent variable, so that its value can be inserted into the parameter dialog box.

The user inputs number of timesteps and the spacing of the timesteps (linear, logarithmic,...), which is used to create a suitable SampleList (see {{src|ascend/integrator/samplelist.h}}) containing the values of the independent variable for which solution values are to be output/recorded. Actually, the stuff that assigns the SampleList contents is C++ code from {{src|pygtk/integrator.h}}.

Associated with the integrator is an IntegratorParamsDefaultFn, which will create the list of parameters that configures the integration engine. The integration engine provides the initial list; the GUI is then used by the user to make any adjustments to the predefined defaults.

We would like to migrate towards a solution that allows default values for these parameters to be specified within the model file, for easier model re-usability.

=== Analysis ===

When all the timestep (SampleList) information is specified and the integrator parameters are set, the ''integrator_analyse'' function is called. This function allows the integrator engine to do any necessary preparatory analysis of the model. This may include re-ordering the equations and variables for optimal solving, or creating internal data structures relating derviatives and their base variables.

A default analysis function, <tt>integrator_analyse_ode</tt> is provided ({{src|ascend/integrator/integrator.c}}) that is used by the [[LSODE]] and [[DOPRI5]] integrators, but other integrators such as [[IDA]] can provide their own function (see <tt>integrator_ida_analyse</tt> in {{src|solvers/ida/idaanalyse.c}}.

In <tt>integrator_analyse_ode</tt>, the call <tt>integrator_visit_system_vars(sys,&integrator_ode_classify_var)</tt> is used to visit all of the variables in the system and classify any that are derivatives or variables for which derivatives are present. The function <tt>DynamicVarInfo</tt> works out the type of each variable (state/derivative/algebraic/independent) and its 'ode_id', then <tt>integrator_ode_classify_var</tt> does the job of building up suitable lists of each kind of variable for later use in the analysis process.

If analysis returns an error of any kind, that typically means that the user has configured their problem incorrectly. In this case, the PyGTK GUI opens a dialog and fills it with the output of the function <tt>integrator_debug</tt>. This function can be used to give suggestions to the user about what may need to be fixed (although the usual error reported mechanism can also be used).

==== IDA ====

The IDA integrator works a bit differently. Currently it looks like overkill, and we're hoping that a re-think will help to streamline this code.

In <tt>integrator_ida_analyse</tt>, we carefully deal with the case where a variable is declared as differential even when a deriv

* <tt>reanalyze_solver_lists</tt>, to update the rels/vars in the system system according to the WHENs
* <tt>integrator_ida_check_vars</tt>, to check for differential variables that are not incident, downgrading 'differential' variables to algebraic variables if no derivative is present, and marking any
* run <tt>integrator_ida_flag_rels</tt>, then
* <tt>integrator_ida_sort_rels_and_vars</tt>.
* <tt>integrator_ida_create_lists</tt> and
* <tt>integrator_ida_check_diffindex</tt>. Then
* <tt>integrator_ida_check_index</tt> checks the index of the DAE system, then
* work out the list of observed variables and store them in <tt>sys->obs</tt>.

TODO complete this section.

=== Solution ===

Once the analysis has been completed, the PyGTK GUI creates an <tt>IntegratorReporterPython</tt> dialog that graphically shows the progress of timesteps as they proceed. The IntegratorReporterPython dialog makes a call to <tt>integrator_solve</tt>, after first setting up hook functions using <tt>integrator_set_reporter</tt> that allow intermediate results to be recorded.

<tt>integrator_solve</tt> makes a call to the specific integration routine provided by the selected integration engine. It is the job of this function to integrate up to each timestep listed in the SampleList and to make calls to the IntegrationReporter at each such point. Some integration libraries will have difficulty providing results for all requested timesteps; in this case, so don't assume that the observer output matches the SampleList in all cases.

In the PyGTK GUI, IntegrationReporterPython looks at the model at records any 'observed' variables (those with <tt>varname.obs_id</tt> set) into a data array in memory in Python. In the Tcl/Tk GUI, the 'observed' values are recorded to a text file that is later loaded into the GUI.

=== Results output ===

When integration has completed, the GUI receives an error message if any problem has occurred.

If all went well, the value of the data array is used (in the PyGTK GUI) to fill the contents of an Observer data table, which is then displayed to the user. This array will contain the timesteps that were requested, together with the values of any variables that had their 'obs_id' value set.

== Data structures ==

This section outlines the key data structures used in communication between ASCEND and the integrator engines.

=== IntegratorInternals ===

This structure contains the bare-bones description of an integrator engine, including the hook functions that are used to 'drive' it, as well as a string and integer identifier for the engine.

=== IntegratorSystem ===

This structure contains the data common to all integrator engines. These include

* pointer to the <tt>slv_system_t</tt> that is to be integrated (contains variable lists, etc).
* pointer to the IntegratorInternals
* pointer to an IntegratorReporter
* pointer to a SampleList
* pointer to internal data owned by the selected integrator engine
* pointer to interface data owned by the GUI or other controlling process.
* solver parameters data structure
* independent variable
* list of 'state' variables ''y''.
* list of 'derivative' variables ''ydot''.
* list of observed variables ''obs''
* other stuff

=== IntegratorReporter ===

This structure provides functions that will communicate integration results back to the GUI or other controlling process.

* <tt>init</tt>, a function that will initialise the reporter, perhaps opening up a window or allocating some memory.
* <tt>write</tt>, a function that should provide a quick status report, perhaps just telling the user the current value of the independent variable.
* <tt>write_obs</tt>, a function that should examine the system and extract the value of any variables that need to be kept. This function is called each time the integrator reaches one of its designated timesteps as specified in the SampleList.
* <tt>close</tt>, a function that can be used to finalise the reporting of results back to the user, deallocating memory, etc.

=== SampleList ===

This structure contains a list of timesteps (values of the independent variable, to be precise) for which output data is to be returned by the integrator. This list must be prepared ahead of time, before the integrator_solve function is called. In contains

* <tt>ns</tt>, the number of sample values in the list
* <tt>x</tt>, an array of double-precision values
* <tt>d</tt>, a dim_type containing the [[DIMENSION]] of the provided sample values (for cross-checking with the dimensionality of the [[INDEPENDENT]] variable. The idea is that the GUI user can provide values of incorrect units (eg time = 10 cm) and we want to be able to catch that before it causes a problem).

== See also ==

* [[External Integrators]]

[[Category:Development]]

Thin-walled tank/Parameterized models

2010-05-13T14:05:24Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

Spreadsheet interface

2010-05-13T14:05:17Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

{{task}}

''Proposal'': create a spreadsheet-like GUI for ASCEND.

This is not the same as integrating ASCEND with existing Spreadsheets. The idea would be to allow models to be created on a free-form grid of some sort, similar to Excel, but really a whole new program using the existing ASCEND back-end to do the calculations.

=== Advantages ===

People are adept at creating models using spreadsheets. It seems to be a natural way to program. I suspect the reasons are twofold:

* '''People are spatially oriented.''' They remember where they put something much more easily than they remember what they called it.
* With every new element in a spreadsheet, they see a new result and can quickly decide if it is correct. '''Programming is incremental.'''

=== Disadvantages ===

* Spreadsheets do not handle arrays well, especially when a model has an array whose size is dictated by a parameter passed from the "outer" model that has it as a part of it.
* Spreadsheets lead to strange 'labels' like 'A5' or 'C24' to refer to cell names; using a language-based model definition, the user is deciding what these labels should be and can give them more memorable names.

=== Thoughts ===

* Perhaps this type of GUI will be suitable only for the construction of one-off models, done quickly, as people often do when programming in Excel. I would like it to be useful for larger models, however, so I do not want it being useful only for small models to be the only outcome.
* Can we imagine using Excel itself as a basis for such a GUI? Or do we have to write our own spreadsheet from scratch? (Twenty years ago there were spreadsheet packages available that one could adopt and modify. Do these still exist?)

=== A thought experiment ===

In ASCEND we create type definitions. Is this something that we can envision doing using a spreadsheet front end? Could we create an instance of a model that we could convert to a parameterized type definition, for example? In an attempt to recover thoughts that we had on this type of front end from over 20 years ago, I will play with creating a model using a spreadsheet like approach. Let's build a model constructed of parts whose type we previously define.

==== Example model building ====

Let’s create a model of a flash unit. I am used to the equations for such a model, it contains parts, and it uses arrays of arbitrary size in its type definitions. We will use the simpleflowsheet01.a4c code as a basis for this modeling.

===== mixture =====

We first must define a mixture. If we were in Excel, we could create an example mixture model by creating a column of y values, one for each component. We would then form their sum by adding up the column. Now,

* can we convert that to a type definition?
* How do we tell Excel that each of the cells corresponding to a y value is of type fraction? Further,
* how do we tell Excel that we want one such cell for each member of a set we call “components?” And
* how do we put the names into “components?”

Note that we would be unable to enforce that the sum of the mole fractions add up to one in Excel without using the “goal seeker” or the “solver” under the tools menu. This, of course, is not how we would envision ASCEND to work. It should be solver for the spreadsheet. We must encode the equations we want enforced in the model. We could do this by putting errors into cells and noting that we want them to be zero at a solution. Other cells could simply be there as intermediate computations. Having said this, how would ASCEND extract equations from a spreadsheet?

Thinking out loud here, let’s see what might be an approach. We should really be trying to discover the wealth of options, but we will start with trying to discover just one that could work.

'''How do we create an ''array'' in a model?''' One possibility would be to select a cell and declare its type to be an array. That would open a new sheet that will contain the array. We need three items (at least) for an array (let’s assume an array is one dimensional so a matrix will be an array of arrays). We need an index set over which the array exists, the base type for the array elements, and the array elements, one for each member of the index set. When the sheet for an array opens, we see these three parts. (Question: should it be a new sheet or should it open as a block inside the current model?) We select the base-type cell, and a list appears that gives us legal base-types. We select one, and its name fills into the base-type cell. Until we give values to the index set, we do not know how many array elements we need, so it appears these should be represented by an icon until we select the index set. We click on the index set and fill in some values - [1..10] or [‘a’,’b’,’c’], for example. As we create these values, ASCEND dynamically creates the cells for the array. We could also fill in the index set by searching for it elsewhere in the parent models containing this array. Or we could leave it unset for the moment – with the cell for the array in the parent model showing in red as it is not yet fully instanced.

We start at the lowest level and create an '''atom definition''' for “fraction.” We do this by opening a new sheet based on the template “atom.” The sheet opens with labeled cells in it for the various parts of an atom. We put values into the lower and upper bounds of 0.0 and 1.0 respectively. There are flags in this sheet (e.g., a fixed flag). We fill in the dimensions for this atom (where? how?).

We are not dealing yet with a lot of issues, but the idea that we could program in this style of interface should be apparent. And, it seems it is in the style of programming in a spreadsheet.

Okay, we have some rudimentary thoughts on the building blocks. We now create the mixture model. We open a new sheet and call it “mixture.” We pick a cell and declare it to be an index set. If we click on it, a template for a set opens which we fill in with element lists, should we want to do that now. We fill in ‘a’, ‘b’, ‘c’, etc.

We pick another cell and select it to be an array with the name ‘y.’ Opening the array sheet, we set the base type to be “fraction.” We select the index set, indicate this set is equal to another, and search through the parent model to find the index set. The next time we open this array within this mixture model, we will see three elements – one for each of the species ‘a’, ‘b’, and ‘c’.

We select a cell in the mixture model and construct a term that is the sum of the elements in the array y less unity. We flag this cell as an equation.

We need yet to think about how to set up methods. We leave that for the time being.

==== molar_stream ====

We next create the model “molar_stream.” New to this model is the FOR/CREATE loop. We also have an included part called a state that is a “mixture.” Some of the other bits are similar to elements in the mixture model.

We pick a cell and label it “state.” We click on it, select “IS_A” as the type cell, and a sheet opens. The sheet has a spot for us to select its type: mixture. When we do, ASCEND fills in what it knows about a mixture from our previous instance. We select “components” at the parent level, select “ARE_THE_SAME,” and search for and equate it to “components” inside the sheet we just called “state.”

How might we construct a FOR/WHILE loop? We want a one-to-one mapping with this statement. We select a cell and declare it to be a FOR/CREATE loop. At this level – i.e., inside this sheet rather than in a new sheet - ASCEND inserts a template of cells (with a box around them, perhaps) that corresponds to this loop. It has an index variable (we label it “i”) along with an index set from which it is to be drawn – i.e., “components.” We tie this index set to the set “components” we created earlier in this sheet. We pick another cell, indicate it is an equation (obviously it will be indexed), and construct the equation. How do we select f[i]? We need not only to pick f but also the general index calculation over which f is indexed, here simply “i”. But this index expression could be of the form 2*i-1. We pick f first. ASCEND sees it is an array of variables. It opens another cell associated with this pick of f into which we construct the index calculation. We select the minus operator, select Ftot (not indexed so no subindex calculation), and then y inside state (indexed and we equate this index with that for f or we construct the index expression over again) that ASCEND provides space for as we construct this equation.

The above FOR/WHILE loop construction makes it clear that programming is by location and not by name – as when we program a spreadsheet. Nice. It also makes it clear that we need to develop an approach for each type of statement we have in ASCEND.

=== It should be fun ===

Since we already know the statement types, this design activity should be fun and not too difficult. Programming the support interface will be the hard part?? At least it would be for me.

-- [[Art Westerberg]]

== Another thought experiment ==

Here's another take on how this stuff could work. The key idea is that this special new spreadsheet would allow relations to be entered into cells, such as "<tt>C5 == B4</tt>". Then, cells like that would provide a visual clue about the convergence status of the relations they contain.

Cells with fixed values would have to be tagged in some way. Same as the [[FIX]]/[[FREE]] functionality we use at the moment.

Arrays would be handled as sequences of cells. FOR loops would be done using relative indexing, the same as for standard spreadsheets. Stuff like [[SWITCH]] statements could be handled using something similar to the current 'IF' function of spreadsheets. This might require some changes to the way that conditionals and handled in libascend.

Models could be declared by drawing a box around a number of cells and declaring a name for the component. Parameters would need to be defined by tagging the necessary cells. Then, this set of cells could be called in the same way as an equation, eg "<tt>mymodel(A4, B5)</tt>". When the submodel was entirely converged, it might show the cell in green. If not, the cell could be double-clicked and an instance of the originally declared model would open, showing all the internal variables.

In additional to all this, there would be a need to specify the [[REQUIRE|REQUIREd]] outside sheets, for model reuse. This could be done using something similar to the Excel add-in loader interface; it would be a list of files loaded to support the current sheet.

Documentation comments could easily be added throughout the sheet, perhaps with a simple ' prefix in such cells.

Units of measurement could be handled as a suffix entered into cells. Cells could have their units of measurement changed, and values would be automatically converted. A (fixed) cell would simply remember the units entered by the user.

Minimum and maximum values for cells would be configurable by right-clicking. Variable types would not be present in this system, but dimensional checking would still be possible and could be helpful in alerting users to input errors in realtime.

With the above approach, it would be fairly simple to build up complex object-oriented conditional models, including model re-use, in a free-form way not currently possible in ASCEND. IT wouldn't be hard to set up the spreadsheet GUI to export the necessary variables and equations to the solver.

Dynamic modelling might even be possible in this scenario, although how dynamic modelling data could be represented to the user would be more difficult to work out.

I think that a METHODS system could be worked out, using a Javascript-style dynamic object model. A scripting layer, similar to Visual Basic in Excel, would be allowed to augment MODEL definitions with methods, and these methods would be able to access and set internal variables of the models. Then, these methods would be callable from other places in the sheet. A special method could be run whenever a model sheet was instantiated and/or a file loaded.

<br />
-- [[John Pye]]

[[Category:Proposed]]

Initial-value modelling

2010-05-13T14:05:06Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

<div class="notice metadata" id="outdated" style="border:solid 2pt orange; width:70ex; background-color:#FFEEDD;padding:4px;margin-bottom:6px">''This article is '''outdated'''. You can help out by <span class="plainlinks">[http://ascendwiki.cheme.cmu.edu/index.php?title=Initial-value_modelling&action=edit updating it]</span>. ''</div>
''See also [[Dynamic modelling]]''

This task is to extend ASCEND's ability to solve initial value differential-algebraic problems. Such problems comprise a mixture of ordinary differential and algebraic equations. The "twist" to this extension is to convert the integration equations for stepping the ODEs into ASCEND models and, initially, to use methods and a Tcl script to do the stepping. In this manner, we do not need to add any new solver code to ASCEND.

Attached (<a href="/images/9/98/DifferentialAlgebraicEqn.pdf" class="internal" title="DifferentialAlgebraicEqn.pdf">Media:DifferentialAlgebraicEqn.pdf</a>: HOWTO chapter for solving DAE initial value models) is a .pdf file documenting the effort to date. It is in the form of a HOWTO in the ASCEND documentation. The code (in its current state) will be added here soon.

See also [http://www.cs.cmu.edu/~ascendFTP/pdffiles/AscendIVP.pdf]
<br />

== Current System ==

The following describes the current system - which is NOT that described in the above .pdf file. It corresponds to the solving of the following DAE models and scripts: dyn_flash.a4l, dyn_column.a4l, dyn_separation_demos.a4s, dyn_tank.a4c and a4s.

To understand the current system, the following 10,000 ft view of the ODE solving process and its history may be useful. The IVP integrators for strict ODEs exist at a level completely separate from the details of solving nonlinear square algebraic systems. All an integrator needs in most cases is ydot=f(y) (FEX) and dydot/dy (JAC). JAC can be produced by a simple trick of linear algebra (this is seen in tcltk/interface/Sensitivity.c).
The solution of the time-marching equations (find new y given ydots) is handled in LSODE; the computation of ydot given a fixed state-variable set y is done using the conventional nonlinear solver. If the nonlinear solver has a structural singularity with the states y fixed, either the model is ill-posed or the DAE index of the related DAE problem is greater than 1.

[[Image:integ_data_1.jpg]]

The required math is easy. The required analysis of the model instance DAG to produce flat representations takes place in two stages.

* stage 1: fix the state variables y to form a well-posed problem, free the derivative ydot, and solve the nonlinear algebraic problem for a consistent initial condition. This is the role of the slv_system_t in the diagram.
* stage 2: collect the y and ydot pairs from the instance tree in a format useful for ODE solvers and begin the time-marching iteration. The integrator is allowed to change the values of the y variables in the instance tree as time is moved forward. This is the role of the Integ_system. The NLA solver is used to compute the needed ydot values at each t and test y. The linear sensitivity analysis is used to compute JAC as needed. JAC may be dense or sparse in reality, but for ascend purposes it is always stored as dense though it may be sparse in most PDE/chem-mech-eng problems. This is a potential subject of optimization, but a better use of limited resources would be in making the DAE solving approach that Art is suggesting above more user-friendly.

The user interface (how hierarchical, reusable dynamic models get connected to IVP solvers) is described in <a href="https://pse.cheme.cmu.edu/ascend/ftp/pdfHowto/howto-ivp.pdf" class="external text" title="https://pse.cheme.cmu.edu/ascend/ftp/pdfHowto/howto-ivp.pdf" rel="nofollow">howto-ivp.pdf</a>. The approach taken to pairing y with ydot variables is by assigning a matching integer index value to each using METHODs. This was a "no language changes required" prototype. It can be used to handle DAEs or ODEs. It is slightly cumbersome (and definitely "busy work") to require the user-written state identification and pairing methods; additional syntax has been desired for a long time.

-- [[Main.BenAllan]] - 01 Jun 2006

<hr />

Syntax extensions require in all but the most trivial cases substantial community negotiation and an eye for where ASCEND is going and has been. The big picture for differential syntax is that we want:

* to be able to handle the declaration of PDEs as well as ODEs (eventually).
* to avoid making a special case of time in the language (though in specific models it's fine).
* to make sure the syntax is compatible with WHEN statements being used to model dynamic discontinuities of all sorts.
* to have an integrator version that handles root-finding and DOF changes so discontinuities are converged properly.

It should be noted that boundary descriptions are already part of the language per the conditional modeling work of Rico-Ramirez.

Some of the basic concepts that have been already devised, but not implemented are:

* Declaring an IVP independent variable of any name and dimensionality, and doing it more than once in the same model as (e.g. time) one variable is not necessarily the only variable that might be useful in ivp modeling as the independent variable.
* Declaring a differential state of any solver_var type.
* Declaring a derivative wrt a state and an independent variable using regular atom types in order to get bounds and scaling correct (yes, derivatives do need bounds and scaling in most physical systems). A tricky case that must be handled in a principled way is the definition of an array of derivatives given an array of states, bearing in mind that ascend sets are unordered sets. In the compiler, sets are really documented as, "arbitrarily and consistently ordered", such that if two set instances contain the same elements, any FOR operation which is executed over one set will process the matching elements in the same order for the other set.
* Defining the domain of an independent variable for IVP or PDE. This likely is different from the '''bounds''' on the same variable, because the domain affects the dependent variables in a PDE.
* Leaving a declared state OUT of the set of states to be solved for with the IVP solver.
* Leaving a derivative OUT of the set of variables to be solved for with the NLA solver.
* Defining an "espilon after" (t+) for making statements about discontinuities; the implications (is it an entire shadow model lurking?) are tricky.

-- [[Main.BenAllan]] - 02 Jun 2006

<hr />

Ben has outlined some very important thoughts we need to discuss in his list above.

I believe there are (at least) two major issues for creating a new DAE solver in ASCEND - if that were our only short term goal. One involves getting the math right. This I hope I have done in writing the .pdf document above and in writing and testing the approach in the models in the folder trunk/models/westerberg/ivpNondimensional in the subversion repository. (Note that these models do not install when creating and installing ASCEND so look for them only in a code checkout.) The second issue is to add to the language the ability to identify the independent variable (e.g., time or distance) and to associate each state with its derivative with respect to the independent variable. This latter could be by adding statements of the type:

'''INDEPENDENT VARIABLE t;'''
'''STATE ppp HAS DERIVATIVE dpppdt;'''

where t, ppp and dpppdt are user names.

Issues that arise when making this type of declaration are:

* several models may declare the independent variable. It has to be the same variable for all models, requiring that it be aliased or a passed parameter from on high or some such thing.
* IF we want the integration equations (e.g., the bdf equations) to be ASCEND models, there has to be a way to associate these equations to the states and their derivatives. My approach in the .pdf document requires me to put these into vectors - not a nice thing to have to do as it requires me to identify in my modeling all the states and their derivatives and map them into these vectors. The strength to my approach is that I can have a variety of integration equations (e.g., bdf or RK4 or whatever) that I write and add to the system strictly as models and not as C code. '''This will be a sticky issue we need to discuss.'''

To restate this last point, if we have the DAE solver (which will be an SLV solver in C) collect the states and their derivatives by finding all declaraions and then associate integration equations with each of them, then how are these equations added to the ASCEND model so the compiler creates its solve system for the model plus these equations (and where these equations are my choice as I have written them as an ASCEND model)? Maybe all this just requires some clever ASCEND modeling that I have not yet thought enough about how to do??

-- [[Main.ArthurWesterberg]] - 08 Jun 2006

<hr />

I'm anti the "x HAS DERIVATIVE y" syntax. I think it's wordy and "y = diff(x)" or "y=der(x)" would be better (it eliminates the need for extra lines in the model declaration). Multiple-word syntax tokens considered harmful: we need to make the ASCEND language more compact (as evidenced by the fact that you felt it necessary to write a macro package for typing models in Emacs).

We have a key problem here: should ASCEND display an instance hierarchy that corresponds to the model that was declared by the user, or should it show its '''internal''' instance hierarchy? This latter, in the case of Art's approach will involve lots of addition curve-fit variables and derivatives, etc. I am in favour of showing only what the user has declared: What ASCEND displays should fit with the user's mental model, rather than the other way around.

-- [[[[Main.JohnPye]]|[[Main.JohnPye]]]] - 13 Jun 2006

<hr />

I am not for a more compact language. We were deliberately wordy, and I have never regreted it. ASCEND is nice because one can guess meaning from the words used. I like self documenting languages. APL (a long time ago) was so compact an expert in it would always misunderstand any program longer than a couple of lines, even if he had only written it a day before. One line of code could about jump through hoops. It did matrix operations with very compact syntax.

Are you suggesting using der(x) (for example) as the derivative of x with respect to the independent variable? y = der(x) only make y equal to der(x); it is NOT defined as der(x) using an equals statement - unless you overload the equal sign (I am against that).

I would have to think of the implications of using der(x) as the derivative of x. How would I give an initial condition to der(x) (which looks a lot like a function and not a variable in the model)? For steady-state, I would like to fix der(x) to be zero, for example. Ben also noted above that der(x) needs bounds, etc. If der(x) is to be looked at as a variable, then it has a different format from other variables (not good). When I think of DAE models, I really do think of the derivative of x wrt the independent variable as another variable in the model. So I do want it to be a variable that I can use in an equation (for example, to square it), bound it, give it nominal values to, give it initial guesses for, etc. My conclusion from this: der(x) has to be a variable, and der(x) is not a good syntax for it.

-- [[Main.ArthurWesterberg]] - 13 Jun 2006

<hr />

I have an idea that may do all the things for which we all have been asking to model and solve IVP DAEs. It is motivated by John insisting we use a form like y=diff(x) to relate the derivative of x wrt time to the variable y and Ben and I arguing that we do not use this form. This idea would NOT require us to modify the compiler, it would also allow one to use whatever model -- as an ASCEND model -- one wishes to do the integration, and it would NOT require one to run around the model manually to find all the derivatives and map them into a vector to pass to the integration routine. It should only require us to write a solver in C, as with our other solvers. It looks a lot like the statement that Ben has suggested and that John has suggested - yes, both.

Use statements of the form

<pre> dxdt IS_A speed;
x IS_A length;
t IS_A time;
</pre>
<pre> derivx IS_A derivModel(dxdt, x, t);
</pre>

I can use IS_REFINED_TO to upgrade any base derivModel to whatever form I wish it to have, where the refinement would bring in the actual polynomial equation to use - e.g., BDF or RK4. The solver would simply have to find all the instances of derivModel in a model to discover what are state variables when it is time stepping, integration error controlling, next poly order predicting and "stopping condition" checking. I could in principle have a different derivModel refinement for every state variable - a nice twist. So I could use different kinds of polynomials for different variables.

One issue: I wonder how we could enforce that all independent variables are the same one variable in the entire problem - the UNIVERSAL statement (seldom used of late in ASCEND) might help.

We can get away with this approach because integration polynomials only ever involve the state, it derivatives and the independent variable. There are no references to the values for other variables in these polynomials. I suspect this would also let us handle PDEs in a similar way.

The derivModel will set aside the space needed for past values of derivatives and states. The user's model, which includes this statement for each state, will define the physical relationship among the states and derivatives. derivModel will only supply the numerical integration equations.

To handle predicted variables that are not state variables (such as an algebraic variable whose value I wish to predict to aid converging at each time step or that I wish to use as a stopping condition), use a statement of the form

<pre> algegm IS_A algebModel(m, t);
</pre>

and the system can collect these and use a different polynomial model to use for predicting.

I cannot see any obvious holes in this - yet. If I am not kidding myself on it, then it is actually a demonstration that the ASCEND language is doing a nice job in extending to this new type of problem with the features it already has.

-- [[Main.ArthurWesterberg]] - 16 Jun 2006

<hr />

I decided to see just how difficult it would be to create the models
required for the approach I just suggested. I committed a new model
into models/westerberg/ivpNondimensional/ivp[[NonNew]] that you may wish
to examine.

Basically, for every state variable (i.e., variable y for which one
writes an ODE to define dydt for it), include the following statement
in one's ASCEND model:

<pre>defineState_Velocity: stateVel IS_A diff(accel, vel, t);
</pre>

There can be a variety of diff models in one's library, and one would
use REQUIRE at the top of the model file to select which one wants at
this moment.

This is really all there is to it.

The diff model adds polynomials of order 12 to the ASCEND model, for
the current point and each of twelve past points, for both relating y
to a polynomial in t and relating dydt to a different polynomial in t.

<pre>These are the only equations one needs to add to provide the
</pre>

numerical integration equations.

The solver will control which of these equations to include at the
current time step by setting equation include flags and variable fixed
flags appropriately. Mimicing how Lsode steps (as we would implement
it), the solver has to choose the order polynomial to use for the next
step. Let us suppose it chooses order 3. This means one will use
third order polynomials. Only coefficients a[0] to a[4] would be
nonzero. The solver would set the remaining, a[4] to a[12], to zero
and fix them. Based on whether it is integrating a stiff problem or a
nonstiff problem, the solver has to choose whether to include y =
poly(t) or dydt = poly(t) equations for the current and up to three
past points. Both kinds of polynomials are in the model for all
twelve past points. The solver would uninclude all those not wanted.

That is the essence of getting the integration equations into the DAE
model directly for solving them with the user's DAE model equations.

The solver (written in C) would have code that corresponds to the
methods I wrote to do the error checking, to decide the order to use
next, to predict the next point, to check for stopping conditions,
etc.

All in all it looks pretty straight forward and a lot simpler than my
previous code. Adding the diff model for each state variable made the
models a lot less complex. Also always adding 12th order polynomials
and killing the higher order terms by setting coefficients to zero and
fixing them made what had to be added easier.

== The current view ==

The current view is that the integrator API as currently shared by IDA and LSODE will more-or-less stand, but there will be more changes to the way in which integration systems are analysed. We currently propose to use syntax something like

<pre>DERIV(dx_dt,x);
</pre>

This will add a 'LINK' of a specific type ('time-derivative', perhaps) between these two variables, which the analysis routines will be able to find and use when preparing the model for solution by the integrator [[IDA]] or [[LSODE]].

== Blocking in dynamics models ==

The following diagram is helpful in understanding the different types of variables and relations that are present within a dynamic model

[[Image:DAE-incidence.png]]

[[Category:Outdated]]
[[Category:Development]]

ATOM

2010-05-13T14:04:54Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

<div>''This article is incomplete or needs expanding. Please help out by adding your comments.''</div>
The '''ATOM''' statement is used to declare new variable types in ASCEND. These can be symbol, boolean, integer, or real-valued. The capabilities of ASCEND in solving models with these types of atoms depends on what solver is used. The ATOM statement is used to refine the definition of base variable types. You can add additional parameters such as upper and lower bounds, and scaling parameters, as well as defining the [[Dimensions]] for the variable.

Atom types may declare attribute fields with types real, integer, boolean, symbol, and set. These attributes are not independent objects and therefore cannot be refined, merged, or put in a refinement clique ([[ARE ALIKE]]).

The syntax for declaring a new atom type is

<source lang="a4c">ATOM atom_type_name REFINES variable_type
«DIMENSION dimension_expression»
«DEFAULT value»; (* note the semicolon *)

«initial attribute assignments;»
END atom_type_name;</source>

An example is the declaration of the [[solver_var]]:

<source lang="a4c">ATOM solver_var REFINES real DEFAULT 0.5 {?};

lower_bound IS_A real;
upper_bound IS_A real;
nominal IS_A real;

fixed IS_A boolean;
fixed := FALSE;
lower_bound := -1e20 {?};

upper_bound := 1e20 {?};
nominal := 0.5 {?};

END solver_var;</source>

Note in the above the wildcard dimension, {?}.

For more detail, see the [[Category:Documentation|user's manual]].

See also [[Units of measurement]].

[[Category:Incomplete]]
[[Category:Syntax]]

Remote Virtual Windows

2010-05-13T14:04:45Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

Here is some information on setting up Windows XP as a '''virtual''' operating system on your Ubuntu system at 'work' so that it can be accessed remotely via VNC from 'home'.

Why would you want to do that? (1) you only have one licensed copy of Windows and (2) you normally run Linux for whatever reason, you only have one work machine, and you don't want to have to shutdown your work machine just so that you can access Windows from home via [http://www.tightvnc.com VNC] or RDP. It might also be that you want to run a [[Installing_a_Buildbot_service_on_Windows|Buildbot]] for Windows, but you don't have spare machine available, as was my case.

What do you need? Your 'work' system needs to be a fairly recent and fairly fast machine with probably at least 1GB but more likely 2GB+ of RAM. In order to run [http://sourceforge.net/projects/kvm KVM] on it, you will need a recent 'Core Duo 2' or 'Xeon' processor or the AMD equivalent.

How well does it work? With Core Duo 2 2.1 GHz 2 GB RAM system at 'work' and a tired old P4 2.4 GHz running Fedora 7 via a fairly slow ADSL connection at 'home', it worked very well, provided you can make use of TightVNC to provide compression of the transmitted Windows session. This method doesn't tie up the machine at work, either: it doesn't need to be booted into windows, and it can be used by other users for other things, serving up files or a website, etc. The virtual Windows system can be started and stopped remotely, and can stay running even if your home connection is a flakey.

If you do try this stuff out, please [[User:Jpye|let me know]] with an email or some edits on this page!

== Set up virtual Windows on your server ==

At work (or whereever your server is) we assume you are running Ubuntu. Follow the instructions there for setting up Windows XP as a Kernel Virtual Machine (KVM). Instructions for this part are <a href="https://help.ubuntu.com/community/KVM" class="external text" title="https://help.ubuntu.com/community/KVM" rel="nofollow">here</a>. This step takes a while, and will whirr your CD drive for a while, but is fairly straight forward provided you note the thing about pressing 'F5' at the appropriate moment.

While Windows is installing, make sure your Ubuntu machine has got <tt>sshd</tt> installed and make sure that port 22 is open on your firewall (eg Firestarter) if you are using one. Make sure you can access your machine from outside the office. You may need to set up a Dynamic DNS name if you don't have a static IP address on your work machine (information <a href="https://help.ubuntu.com/community/DynamicDNS" class="external text" title="https://help.ubuntu.com/community/DynamicDNS" rel="nofollow">here</a>)

Once Windows is installed via KVM, launch it localling using the 'kvm' command as outlined in the above instructions. Install [http://www.tightvnc.com TightVNC] and set it up as a service (you will be asked for a password). Set TightVNC to accept connections to port 5900. You can turn off the HTTP feature.

In your virtual Windows system, open up the Windows firewall on port 5900 to allow VNC connections.

== Starting up your virtual Windows system ==

You need to run your virtual Windows system from within the utility program called 'screen'. This allows you to start it remotely, and for it to keep running, even if you connection goes down.

From your home system, open an SSH connection to your work system and type 'screen'.

Once <tt>screen</tt> has loaded (it will show you some basic information before giving you a new shell prompt), type <tt>kvm -redir tcp:5909::5900 -smp 2 -vnc :8 -k en-us -usbdevice tablet -no-acpi -m 512 -cdrom /dev/cdrom .kvm/winxp0.img</tt>.

This will start your virtual Windows system, although you won't see anything yet, and the command won't complete. You have now got an (invisible) windows session running on your server. To access it, we are not going to use the VNC server provided by KVM/QEMU but instead we are going to connect to the *virtual* TightVNC server that we installed on the virtual machine.

Close the SSH connection you your work system by closing the terminal window. Because you ran 'kvm' from inside 'screen' it will continue running even after your SSH session has been closed.

== Connect to your server with correct port forwarding ==

We'll assume your '''home''' system is Fedora 7. If it's Ubuntu or Windows or something else, you'll need to work out your own approach.

First, install TightVNC on your '''home''' system. On Fedora, you can just use the .rpm package from [http://www.tightvnc.com].

Next, set up TightVNC on your home system so that it uses the right compression methods by default, and set it so that it uses full-screen display. Assuming you are on Linux, you can set up your TightVNC settings for fullscreen use by editing/creating the file <tt>~/.Xresources</tt> so that it contains:

<source lang="a4c">! vncviewer
Vncviewer*encodings: copyrect tight hextile zlib corre rre raw
Vncviewer*fullScreen: True
Vncviewer*grabKeyboard: True
Vncviewer*compressLevel: 7

Vncviewer*qualityLevel: 3</source>

You may need to load these settings explicitly by typing 'xrdb ~/.Xresources'.

Next, optionally, check that your home system has an SSH Private Key, and add you SSH Public Key to your office server:

# On your home system, type 'cat ~/.ssh/id_rsa.pub'.
# Then, copy that text to the end of the file '~/.ssh/authorized keys' on your office server.

Next, add a 'custom launcher' to your GNOME panel on your home system. Set the command to 'vncviewer -via yourname@yourserver.example.com :9'. This will use an SSH tunnel to connect to your office machine on port 5909, which is the port that forwards through to your virtual Windows system.

TightVNC should now ask you for your VNC password. This is the password you set when installing TightVNC on your virtual Windows system.

After you have entered the password, Windows should show up in a full-screen view of your remote virtual Windows system. To exit from viewing the remote session, enter 'F8' then click 'Quit viewer'. You can re-launch vncviewer to get your virtual Windows system back again, as long as your SSH tunnel connection to the server is still open.

== Shutting down virtual Windows ==

To shut down your virtual Windows system, just connect to it as above and shut it down as you would a 'real' Windows system. Then, open an SSH connection to your office system and type 'screen -r'. This should show up either (a) the still-running 'kvm' process or (b) some output, possibly saying 'Aborted (core dumped), along with a new command prompt. If KVM is still running, press ctrl-C. Virtual Windows is no longer running

== Restarting your virtual Windows system ==

As for shutting down Virtual windows, open up your 'screen' session by typing 'screen -r' then re-run 'kvm' using the same command as last type (<tt>kvm -redir ...</tt>). As before, you can close the SSH session once you have started kvm.

== Security ==

The only security issue here is that you have opened up your 'work' machine to SSH connections. SSH connections are always encrypted and are secure providing your passwords are secure. If you want to improve security, consider setting your firewall to only accept SSH connection from certain IP addresses or a range of IP addresses.

[[Category:Miscellany]]

EnzymeKinetics

2010-05-13T14:04:37Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

Enzyme Kinetics. (work in progress, feel free to add/edit/correct!)

Consider the following enzymatic reaction (E is the enzyme, S the substrate,
ES an enzyme substrate complex and P the product).

<math>{\mathrm{E}} + {\mathrm{S}} {{{\mathrm{k_1}}\atop{\longrightarrow}} \atop{{\longleftarrow}\atop{{\mathrm{k_{-1}}}}}} {\mathrm{ES}} \stackrel{k_2}{\longrightarrow} \mathrm{E} + \mathrm{P} </math>

The Michaelis Menten equation
is often used to calculate the rate of enzymatic reactions and is arrived at using either
the pseudo steady state (the rate of change of ES with time is small, almost zero)
or the equilibrium assumption (that ES is always in equilibrium with E and S, the first
step in the reaction). We show how this is arrived at and how to solve the equation.

The elementary reactions are:

<math>\frac{d[S]}{dt} = -k_1 [S][E] + k_{-1}[ES]</math>
<math>\frac{d[ES]}{dt} = k_1[S][E] - k_{-1}[ES] - k_2[ES]</math>
<math>\frac{d[E]}{dt} = -k_1 [S][E] + k_{-1}[ES] + k_2[ES]</math>
<math>\frac{d[P]}{dt} = \mathrm{rate} = k_2 [ES] </math>

There are two ways to solve for <span class="texhtml">[''E''''S'']</span> so we can get a
rate expression that includes the substrate concentration and parameters
that can characterize the nature of the enzyme.

The pseudo steady state (PSS) approximation states that we can assume that
<math>\frac{d[ES]}{dt}</math> is zero, while the equilibrium
assumption states that <math>{\mathrm{E}} + {\mathrm{S}} {{{\mathrm{k_1}}\atop{\longrightarrow}} \atop{{\longleftarrow}\atop{{\mathrm{k_{-1}}}}}} {\mathrm{ES}} </math> is at equilibrium. Either of these assumptions/approximations will lead you to the
Michaelis Menten form of the rate expression, written as

<math>rate = -\frac{dS}{dt} = \frac{dP}{dt} = \frac{V_m S}{K_m + S}</math> where
<span class="texhtml">''V''<sub>''m''</sub></span> can be shown to equal <span class="texhtml">''k''<sub>2</sub>''E''<sub>0</sub></span> where

<span class="texhtml">''E''<sub>0</sub></span> is the initial concentration of the enzyme <span class="texhtml">''K''<sub>''m''</sub></span>
is <math>\frac{k_{-1}+k_2}{k_1}</math>. (If you use the equilibrium assumption,
you get a very similar expression, where the <span class="texhtml">''K''<sub>''m''</sub></span> is
<math>\frac{k_{-1}}{k_1}</math> (PSS is considered a better approximation to use)

The PSS approximation is a good one to make, as long as the substrate
concentration is much larger than that of the enzyme (you can check this
by manipulating these concentrations in the model below that includes
the four differential equations, see what happens if substrate is NOT much
larger than Enzyme concentration, the PSS assumption breaks down)

In the PyGTK GUI, you can plot any of the dependent variable (Substrate (S), Enzyme (E),
EnzymeSubstrate Complex (ES) or product (P)) as a function of the independent variable (time)

=== The Michaelis Menten Equation (Simplified Form) ===

<source lang="a4c">REQUIRE "ivpsystem.a4l";
REQUIRE "atoms.a4l";

MODEL lowKm;
dS_dt IS_A rate;
Vm IS_A rate;

Km, S IS_A factor;
dS_dt = -Vm*S/(Km + S);

t IS_A time;
METHODS
METHOD on_load;
RUN default_self;

RUN reset; RUN values;
RUN set_obs;

RUN set_ode;
END on_load;

METHOD default_self;

END default_self;
METHOD specify;
FIX Km, Vm, S;

END specify;
METHOD values;
S := 10.0;

dS_dt := 0 {Hz};
Vm := 1.0 {1/s};

Km := 20.0;
t := 0{s};
END values;

METHOD set_obs;
S.obs_id :=1;
END set_obs;

METHOD setup;
RUN specify;
RUN values;
END setup;

METHOD set_ode;
FREE dS_dt;
S.ode_id := 1; dS_dt.ode_id := 1;

dS_dt.ode_type := 2;
S.ode_type := 1;

t.ode_type :=-1;

END set_ode;
END lowKm;

MODEL highKm;

dS_dt IS_A rate;
Vm IS_A rate;

Km, S IS_A factor;
dS_dt = -Vm*S/(Km + S);

t IS_A time;

METHODS

METHOD on_load;

RUN default_self;
RUN reset; RUN values;

RUN set_obs;
RUN set_ode;
END on_load;

METHOD default_self;
END default_self;

METHOD specify;

FIX Km, Vm, S;
END specify;

METHOD values;
S := 10.0;
dS_dt := 0 {Hz};

Vm := 1.0 {1/s};
Km := 200.0;
t := 0{s};

END values;
METHOD set_obs;
S.obs_id :=1;

END set_obs;

METHOD setup;
RUN specify;
RUN values;

END setup;

METHOD set_ode;
FREE dS_dt;

S.ode_id := 1; dS_dt.ode_id := 1;

dS_dt.ode_type := 2;
S.ode_type := 1;

t.ode_type :=-1;

END set_ode;

END highKm;</source>

=== Solving the Set of Ordinary Differential Equations ===

<source lang="a4c">REQUIRE "ivpsystem.a4l";

REQUIRE "atoms.a4l";

MODEL simple;

dES_dt IS_A rate;
dS_dt IS_A rate;

dP_dt IS_A rate;
dE_dt IS_A rate;
k1, k2, km1 IS_A rate;

P, E, S, ES IS_A positive_factor;

eq1: dES_dt = k1*E*S - km1*ES - k2*ES;

eq2: dS_dt = -k1*E*S + km1*ES;

eq3: dP_dt = k2*ES;
eq4: dE_dt = -k1*E*S + km1*ES + k2*ES;

t IS_A time;

METHODS

METHOD on_load;

RUN default_self;
RUN specify;

RUN values;

RUN set_obs;

RUN set_ode;

END on_load;

METHOD default_self;
END default_self;

METHOD specify;

FIX k1, km1, k2;
FREE dS_dt, dP_dt, dE_dt, dES_dt;

FREE S, E, P, ES;
FIX E, S, P, ES;

END specify;

METHOD values;
ES := 0;

P := 0;
S := 1.0;
E := 0.1;

dS_dt := 0 {Hz};
dES_dt := 0 {Hz};

dP_dt := 0 {Hz};
dE_dt := 0 {Hz};

k1 := 1.0 {1/s};
km1 := 0.02 {1/s};

k2 := 0.02 {1/s};
t := 0 {s};

END values;

METHOD set_obs;
ES.obs_id :=1;

E.obs_id := 4;
S.obs_id := 2;

P.obs_id := 3;
END set_obs;

METHOD set_ode;

S.ode_id := 1; dS_dt.ode_id := 1;

ES.ode_id := 2; dES_dt.ode_id := 2;

E.ode_id := 3; dE_dt.ode_id := 3;

P.ode_id := 4; dP_dt.ode_id := 4;

dS_dt.ode_type := 2; dES_dt.ode_type := 2; dP_dt.ode_type := 2; dE_dt.ode_type := 2;

S.ode_type := 1; E.ode_type := 1; ES.ode_type := 1; P.ode_type := 1;

t.ode_type :=-1;

END set_ode;
END simple;</source>

[[Category:Documentation]]
[[Category:Examples]]

Next-generation ASCEND syntax

2010-05-13T14:04:26Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

{{task}}

''See [[New Compiler]] for motivation, but this page is about nitty details.''

A number of problems with the current system (and its ancient mishmash of Pascal and smalltalk ideas) suggest that a saner way forward than incremental cleanup is to reinvent the language front end and stick with a small language. The ultimate "big language" approach ends with modelica/xml, which we do not care for.

== Objectives ==

Aiming toward 'small-project' and 'portability' and 'easy to learn' and 'integrability' leads to the following design criteria for a new front-end (input language):

* respell the pedantic keyword style of ascend to something which is ergonomic and still clear.
* redesign the use of delimiters for concepts not part of normal procedural languages (equations, set notation, annotations, tables) .
* not expose the user to explicit memory management of the model, unless they are very ambitious.
* provide for methods which may be written in the full syntax and semantics of a standard ISO language without tortuous usage to refer to the ascend model parts.
* eliminate the bulk of the hand-coded compiler/interpreter routines-- leave this work to real compilers like C and interpreters like python. Get rid of everything after compiler Pass1.

== One approach: sitting on top of a 'base' language ==

Derive from some language which is:

* easy to learn.
* already well known with a large, lightweight (and/or else highly ubiquitous and stable) open-source tool base for developers.
* capable of being processed with an open-source, easily modified AST-based engine so that a class in the language can be verified for conformance with ascend modeling restrictions/practices.
* capable of being compiled to binary, to avoid our maintenance of an interpreter.
* capable of supporting multithreaded use, for performance on all modern systems.
* capable of preserving ascend's dynamic typing and glassbox modeling approaches.

Ben has given up on this approach, because C can't support it and everything better than C is worse at meeting the big picture requirements.
Also, what we really want is easy interoperabilty (or embedding) in many languages, not just one.

=== Possible base languages ===

* C++ is the most obvious choice to meet the above criteria, but critically fails the AST-based engine criterion.
* (Abbot went this route) Java is a possibility, but is slow and the common editing environments for it are anything but lightweight.
* Ruby/Python are persistently tempting but so persistently inconsistent that portability is an big issue.
* Fortran 20xx is a possibility, since it has an open-source parser, but then it adds a lot of baggage if we want to apply autodifferentiation.
* C and objective-c, unlike c++, is very parseable and otherwise has the large array of tools needed. The base language compiler error messages are nearly useless, but with an appropriate ASCEND frontend, this could be much improved. In particular, if our dialect of C explicitly bans end-user use of the C preprocessor, much becomes simpler.

Prototyping with several of these, however, show that grafting introspection on to any of the binary-oriented languages ultimately leads to madness. So the alternative is to consider designing a very small language with no imperative statements but eliminate the bulk of the instance structure management by targeting a base language the routine user does not see. The methods section becomes a plain text block that, with perhaps minor automated edits, is then valid code passed to the base language compiler.

* An alternative approach would be to use one of ML, Haskell (or a strict version thereof), or Scheme as a base language. These have the advantages that parsing, analysis, automatic type inference (the used kind for a static type system to as to minimize user type annotations), and generally everything related to programming and reasonable compilation become much easier. Also, if say a miniature strict version of haskell were used, the monad abstraction would be useful for tracking dependencies of what needed to be reevaluated etc when parameters of a model are reset. Additionally with either of these functional languages as substrate, it'd be relatively simple to add some sort of notion of having units for values that can be checked statically/dynamically. (eg m^2, ft, etc). They are also good languages for metaprogramming etc, though very very different approaches are taken in each of the three.

== Eliminate the instantiator bulkiness and thinking about instance memory management issues ==

The maintenance nightmare which is the compiler could be substantially reduced by having a grammar which is simpler and turning the compiler into a family of code generators. Instantiating a model is then just passing processed models through an output phase and running python or gcc or ... on them. '''In this approach, memory management of the instantiation becomes the responsibility of the target language-- ascend is no longer creating a canonical instance tree (beyond Pass1 of the current compiler which is essentially an AST expansion) on which external languages act through limited APIs.'''

== 'Designing out' maintenance errors ==

Simple naming error introduced in maintenance are typically caught by the parser or instantiation. Block nesting errors, on the other hand, are very easy to introduce and often hard to find (or correct if not introduced by the same coder). Syntax can eliminate most such errors by eliminating ambiguity in block end matching. ASCEND4 has the feature. Some people would try to improve it. [[BetterBlockSyntax]] alternatives are discussed.

== Eliminate redundant typing ==

Type declaration in ascend is currently clunky, due to its pascal-ish nature and its long, underscored keywords. Going with any of the mainstream languages is equally clunky. Consider the alternate example:

<pre>// assume any ascend4 feature you don't see revised here will pretty much carry over unmodified (except perhaps lowercase).
// note that if we can get the sections defined properly, we may be able to use '=' a lot of places unambiguously with one
// meaning of '=' defined in each section.
model b
...
ledom
atom pressure extends real
...
mota
model c
x1, x2, q: real;
ledom
model a (somename : symbol_constant) extends c
// sections are with keywords changes, submodels, variables, equations boundaries, methods, etc.
// everything is declared with a (label: type;) where label may be one or more names. type may be parameterized.
interface-
// stuff so we can have more than one parameterization of a type.
// semantics to be determined. Does an 'a' with multiple interfaces yield multiple (implicit) type definitions?
// Is the member list of a type the union of all defined interfaces?
// Can a name be willbe in one interface and isa in another?
// When is an instance created by one interface going to be mergeable with one created by another interface?
changes-
q: pressure; // IRT
x1, x2: merged; // ats
q, x1: alike; // AA (with refinement side effects).
x2: findtype(somename); // dynamic kind irt. currently requires passing a prototype instance.
submodels-
bpart: b;
constants-
s: string; // symbol
order: int; // integer
variables-
b1: real;
b: pressure;
y; // implicit double var named y, or error. design choice
equations-
e1: 2*y = z;
boundaries-
bnd1: y > b;
invariant:
// statements about structure that downstream refinements must not violate at any time
analyzers-
// Definition of OODB-style queries and manipulation of results, eg for building dynamic solver-oriented structures.
// Any item defined in analysis may be referred to in another analysis, but not in model-declarative sections.
// An analysis is not part of the implicit, dynamic typing of ascend instances.
// numeric operators on lists for gradients, blocking, hessians, residuals, etc.
// multi-d arrays of dimensionless numbers with C indexing or ranging ala fortran. slicing ala fortran?
// border-issue: where do we leave off and have matlab/octave begin?
// call() for standard numeric libraries or gate it out to procedural code receiving operator objects?
//// Arguably, all this is doable from any of the tri-semicolon languages, but why not canonicalize the
//// query operations in a form reusable and composable from all target languages?
analysis newton(self)
rlist = collect(basetype=relation);
eqlist = filter(rlist, .included==true, .token[0] == EQ);
done
methods-
 ;;;c;;;
// c-ish code here. basically, pasted into output of conversion to C of the declarative code.
 ;;;;;;
 ;;;python;;;
// pythonic code here.
 ;;;;;;
method x // old style methods deprecated maybe? They got overloaded with a lot of poorly C-ish crap once extended past simple assignments.
dohtem // impossible to get right, on purpose. stop using ascend4-style methods.
assignments-
procedure y (arglist named, typed numeric values and willbe objects only )
'''list''' = value-expression; // strictly assignments only in this section.
end;
ledom
</pre>

Here we see that the labeling ( colon usage) for equations from ascend 4 as consistently applied to all parts.

* This format is pretty simple to parse: except for eqns, bounds, and optional assigments in the constants section and changes sections, it is all lists of names, of which the last must be a type. loops and switches are minor extensions on this.
* no shift key required anywhere, until you get in {} for table and annotation structures.
* The use of ''':''' ''',''' and (on section names)'''-''' is entirely syntactic sugar and could be omitted.

== Scaling to DAEs, PDEs, and all that ==

The notion of analyzers is powerful, but it cannot capture semantics which are not there in the ascend model. We can add semantics via deriving from specific types, but past attempts in this direction with ascend have not proved highly usable or reusable or extensible-- all the semantics gets buried in C analysis implementations.

The lexing and AST analysis of antlr makes defining and maintaining fancy line-oriented syntaxes for operators, domains, domain surfaces and time limits much easier to prototype and play with. It does nothing, on the other hand, to deal with the underlying discretization data for problems on irregular grids.

[http://chapel.cray.com/ Chapel] is an HPC oriented language with a very interesting history and currently under development by DOE/Cray. It has a lot of constructs intended directly for PDE-related algorithms.

== METHODS ==

=== Using C ===

So C-ish code here is interesting. In particular, there's the tremendous problem of the end user addressing (correctly every time) some piece of an ascend model from C. To that end, I propose the following simple filtering rule (it might work for python very similarly):

* Any complete dot-qualified name appearing in the c-ish code will be checked for existence.
** If it does not, it will then checked in the model hierarchy (and if found) converted to the proper C reference form.
** If not found, a warning will come from the ascend C code generator and (invariably) an error will come from the C compiler if the user proceeds.
** If it does not, it will then checked in the model hierarchy (and if found) converted to the proper C reference form.
** If not found, a warning will come from the ascend C code generator and (invariably) an error will come from the C compiler if the user proceeds.
* If it does not, it will then checked in the model hierarchy (and if found) converted to the proper C reference form.
* If not found, a warning will come from the ascend C code generator and (invariably) an error will come from the C compiler if the user proceeds.

Why? ASCEND model structures are dynamic (though this need not be so for the output C, it probably will be to accommodate using the C-instantiated instance under the current GUIs which may request refinement), so they cannot be converted to nested C structs; they must be converted to structs containing pointers to the child instances. Thus in ascend notation a real named a.b.c would probably end up in C as:

<pre>((struct Var *)(self->childlist[2]->childlist[3]->childlist[1]))->value
</pre>

In a nondynamic c generation, it would be:

<pre>a.b.c.value

</pre>

=== Using Python ===

Not enough thought here yet. Imagine the power, though, if combined with analyzers.

=== Using a native ASCEND language for METHODS ===

Today's current methods could keep their syntax and be simply converted (on a fully instantiable model) to equivalent native method in any request language for which there is a filter. Otherwise, we have to keep hauling around an interpreter and debugger for our methods. I would prefer to deprecate them and much of the cruft going along that can be better done directly with new 'native' tri-semicolon methods.

=== 'procedures' ===

Get back to the ASCEND3 simple assignments only scheme. Anything else leads to madness best resolved in tri-semicolon code.

== Proofs of concept ==

Yacc/Lex are completely out of gas when it comes to parser maintainability and extensibility and AST management. Extensibility is a key feature for ASCEND. The only other alternatives going are GLR and ANTLR and boost-spirit. C++ errors are still hopelessly cryptic. ANTLR has an astounding tool stack used heavily in the commercial and scientific computing worlds, including grammar IDE, grammars for C, fortran, Java and C preprocessor. GLR we don't know enough about.

Thus, two grammars and a set of tree-walkers are required for a satisfying language prototype.

* antlr parser of ascend4.
* antlr parser of ascend5.
* tree walker that takes ascend4 parse tree in and puts out equivalent ascend5 tree for all legal ascend4.
* tree walker that takes ascend5 parse tree in and puts out equivalent libascend (C or python?) object for any instantiable type.

The key to understanding the approach advocated here is that antlr parsers generate (for free) an abstract syntax tree (AST) which is essentially our current 'TypeDescription' machinery. Lots (if not all) of the manual goop going on in our yacc 'actions' disappears. The AST can then be passed to a series of ANTLR-described filters for type/symbol resolution and semantic validation. The end result of a validation can then be passed to a tree walker (another antlr filter) which follows the type tree to generate an instance tree equivalent to current ascend4 compiler Pass1 where all MODEL, set, and scalar/array instance structures are known. This 'partial' instance tree is sufficient to discover the implicit types of all the models and generate non-redundant code in C, python, etc. The model thus becomes exactly equivalent to any other traditionally compiled language in performance, including access to GPUs, GUIs, etc.

=== Sample parser ===

John Pye (JP) has done a little bit of a first cut on a possible new ASCEND grammar, [http://ascendcode.cheme.cmu.edu/viewvc.cgi/sandboxes/trunk/antlr/mygrammar.g?view=markup sandboxes/trunk/antlr/mygrammar.g] (open it with ANTLRWorks). The idea was to parse as much as possible, including statements that are given in the wrong place, and to then use suitable error messages to advise the user if the context of their statement is disallowed. Lower-case keywords are used, and operators were simplified a bit. This idea still implements a METHODS language, and has opted for a nice IF..ELSE syntax for conditionals (eliminating [[WHEN]] and [[CONDITIONAL]]) but otherwise, doesn't bring very much that's new.

An example of a file that's supposed to parse using the above grammar is [http://ascendcode.cheme.cmu.edu/viewvc.cgi/sandboxes/trunk/antlr/testmodel.a5c?view=markup sandboxes/trunk/antlr/testmodel.a5c]

JP worked out a framework for relations, expressions, function evaluations (my take on external relations), METHODs (yes, still thinking of keeping those around), declarations, model, and importing of other models and code.

Some ideas that seemed to make sense:

* namespace implementation for imported stuff, as per Python. "import as"...?
* 'import' could replace both REQUIRE and IMPORT.
* external relations should be replaced by external functions that can be poked into any expression or conditional.
* relations, assignments, and comparisons should all use the same '=' operator.
* boolean comparison could be forced using 'bool(...)' casting.
* IF..ELSE statements

Things that will need more thought:

* when external functions return multiple variables, how to do the syntax... thinking that <tt>[var, var,...]</tt> lists would be appropriate.
* haven't given any thought to dealing with arrays yet
* was trying to think about METHOD declarations that could require parameters as inputs, for use from other methods. Am too naive to know how much work would be involved in permitting declaration of local variables within METHODs
* haven't yet attempted FOR-loops.
* parametric MODELs need lots more thought as well
* what do to with constants?
* what do about meta-model data like [[NOTES]], icon info, solve directives, etc?

We would hope to replace the current compiler with a sequence of AST tree-walkers: checking the context of things, checking and assigning identifiers, etc.

=== First cut at ASCEND4 parser using ANTLR ===

Here's my first cut at this. No actions, just a grammar. No syntax errors, but not tested/debugged on real model files yet -- [[User:Jpye]]

* [http://ascendcode.cheme.cmu.edu/viewvc.cgi/sandboxes/trunk/antlr/ascend4.g?view=markup sandboxes/trunk/antlr/ascend4.g]

[[Category:Proposed]]
[[Category:Development]]

Category:Tutorials

2010-05-13T14:04:14Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

<div id="mw-pages">
<h2>Pages in category "Tutorials"</h2>

The following 8 pages are in this category, out of 8 total.

{| class="wikitable"
|-
|
<h3>H</h3>

* [[How to begin modelling with ASCEND]]
<h3>T</h3>

* [[TclTk Quick Guide]]
|
<h3>T cont.</h3>

* [[Thin-walled tank]]
* [[Thin-walled tank/Adding methods to a model]]
* [[Thin-walled tank/Arrays]]
|
<h3>T cont.</h3>

* [[Thin-walled tank/Building complex models]]
* [[Thin-walled tank/Introduction]]
* [[Thin-walled tank/Parameterized models]]
|}
</div>
[[Category:Documentation]]

Object-oriented modelling

2010-05-13T14:04:04Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

<div class="notice metadata" id="stub">''This article is a '''stub'''. You can help out by <span class="plainlinks">[http://ascendwiki.cheme.cmu.edu/index.php?title=Object-oriented_modelling&action=edit expanding it]</span>. ''</div>
This page overviews the object-oriented capabilities of ASCEND.

== <tt>MODEL</tt>s built from <tt>MODEL</tt>s ==
The simplest object-oriented capability of ASCEND is to create models as aggregates of smaller models:

<source lang="a4c">MODEL tank;
V IS_A volume;
rho IS_A density;

mdot IS_A mass_rate;
Vdot IS_A volume_rate;
Vdot = mdot * rho;

END tank;

MODEL pipe;
mdot IS_A mass_rate;

rho IS_A density;
END pipe;

MODEL tank_and_pipe;

T IS_A tank;
P IS_A pipe;
T.rho, P.rho ARE_THE_SAME;

P.mdot, T.mdot ARE_THE_SAME;
END tank_and_pipe;</source>

== Model refinement ==

As well as aggregating models to producing models from smaller parts, one can refine a model of one type to make something more specialised, using the [[REFINES]] keyword.:

<source lang="a4c">MODEL vessel REFINES tank;

p IS_A pressure;
R IS_A gas_constant;
n IS_A factor;

T IS_A temperature;
p*V = n * R * T;

T_amb IS_A temperature;
T = T_amb + 20 {K};

END vessel;</source>

Here, both new variables and new relations were added. Note that it is possible only to add new relations; relations in base models can not be removed in refinements of the base model (although using the <tt>included</tt> property of a relations, one can gain something like that ability).

== Parameterised models ==

Models can be set up so that they require certain externally-defined parameters at the time when they are instantiated. For example:

<source lang="a4c">MODEL pump(
in WILL_BE pressurepipe;
out WILL_BE pressurepipe;

);
dp IS_A pressure;
out.p = in.p + dp;

END pump;

MODEL pumped_thing;
L1, L2 IS_A pressurepipe;

P IS_A pump(L1,L2);
END pumped_thing;</source>

These models show that for parameterised (ie parametric) models, you must first declare the sub-models using <tt>IS_A</tt> declarations, then you can place them into your parameterised declaration as <tt>pump(L1,L2)</tt>, which is the name of the ''type'' of model, followed by the specific ''instances'' of the parameters you want.

Further refinement of parametric models is possible using a [[WHERE]] clause following the [[REFINES]] clause.

== Refinements after declaration ==

The <tt>IS_REFINED_TO</tt> declaration allows one to start off by declaring a part to be a base-type and then refine that part to be a more specialised type with a subsequent call. This allows for example arrays of hetergeneous objects to be created.

<source lang="a4c">MODEL flow_sequence;

E[1..3] IS_A flow_equipment;
E[1].out, E[2].in ARE_THE_SAME;

E[2].out, E[3].in ARE_THE_SAME;
E[2] IS_REFINED_TO flow_meter;

E[1] IS_REFINED_TO flow_pump;
E[3] IS_REFINED_TO flow_tank;

END flow_sequence;</source>

The more specialised types (here flow_meter, flow_pump and flow_tank) must be refinements of flow_equipment - e.g.,

<source lang="a4c">MODEL flow_meter REFINES flow_equipment;

....;
END flow_meter;</source>

== Refinements and merges after instantiation ==

ASCEND model instances are dynamically typed. While using a compiled model instance, and using the Tcl/Tk GUI for ASCEND, any instance part can be interactively merged with another compatible part or refined to a derived type to debug the model. This allows interactive exploration of the mathematics without requiring a rewrite of the input files at every step. This practice is not universally endorsed, but the Script logging capability guarantees that all such changes can be captured by the careful modeler and the final set reintegrated in the model source files.

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

Steam properties

2010-05-13T14:03:54Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

== Background ==

In order to accurately model large-scale power systems such as boilers and steam turbines, accurate correlations for steam properties are required. The [http://www.iapws.org International Association for the Properties of Water and Steam] has industry-standard correlations for water and steam properties at pressures up to 10MPa and temperatures up to 1073 K. Higher temperatures are possible too, but not at the full range of pressures. These correlations are in many cases stipulated requirements when consulting engineers are contracted to perform analysis - in order that competing proposals are competing on a fair basis. In large-scale design, even quite small variations in steam properties can result in large differences in overall cost estimates.

The current {{src|models/thermodynamics.a4l}} library in ASCEND does not allow for compressibility of liquids and is therefore too simplistic for use at the elevated pressures seen in large-scale power systems.

== Connection to freesteam ==

[http://freesteam.sourceforge.net Freesteam] provides a free open-source implementation of the standard IAPWS IF-97 steam properties correlations for use with ASCEND via the [[external relation]] mechanism. Example models using these property correlations include those in {{src|models/johnpye/rankine.a4c}}, which demonstrate a range of steam power cycle calculations.

== IAPWS-95 Implementation ==
<div class="notice metadata" id="outdated" style="border:solid 2pt #FDB; width:70ex; background-color:#FFF8F4;padding:4px;margin-bottom:6px">''This section is '''outdated'''. You can help out by <span class="plainlinks">[http://ascendwiki.cheme.cmu.edu/index.php?title=Steam_properties&action=edit updating it]</span>. ''</div>

The [http://www.iapws.org/relguide/IAPWS95.pdf IAPWS-95 (pdf)] steam properties correlations have been implemented and can currently be used to obtain properties of single-phase steam. We are working on getting a stable two-phase model that is able to correctly accomodate the saturated region using a separate IAPWS correlation for the [http://www.iapws.org/relguide/supsat.pdf saturation curves (pdf)].

This work in ASCEND is to facilitate modelling of solar thermal and conventional power station systems.

For further information about IAPWS correlations and a list of some other IAPWS-savvy software, see [http://freesteam.sourceforge.net Freesteam].

To see the current state of the steam tables work, go over to John Pye's ASCEND models at {{srcdir|models/johnpye}}.

== Other implementations ==

There is some interesting information to be gleaned from the Modelica ThermoFluid library, [http://sourceforge.net/projects/thermofluid]. This set of Modelica/Dymola models includes IAPWS-IF97 as well as some interesting although very complex approaches to the problems of modelling thermodynamic processes involving water and steam.

== See also ==

* [[Thermodynamics with ASCEND]]
* [http://freesteam.sourceforge.net freesteam]
* [http://cantera.sourceforge.net/documentation.html Cantera] (a C++/Python chemical reactions toolkit)
* Sublimation curve from IAPWS: {{src|models/johnpye/sublimation.a4c}}

[[Category:Outdated]]

Regression Testing

2010-05-13T14:03:44Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

WILL BE THE SAME

2010-05-13T14:03:34Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

'''WILL_BE_THE_SAME''' is used in [[object-oriented modelling]] to force equality of parameter instances within the [[WHERE]] list.

Example:

<source lang="a4c">MODEL constant_flow_rate(
inlet IS_A steam_stream;
outlet IS_A mass_rate;

) REFINES steam_equipment(inlet, outlet)
WHERE(
inlet.mdot, outlet.mdot WILL_BE_THE_SAME

);
mdot ALIASES inlet.mdot;

(* ... *)
END constant_flow_rate;</source>

See also [[WILL_BE]], [[ARE_THE_SAME]].

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

Real-time ASCEND/Solver

2010-05-13T14:03:24Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

←back to [[Real-time ASCEND]].

Contributed by: [[Dipak Chirmade]]

== Real-time solver ==

=== Runge Kutta based single step solver ===

''''' Work in progress! '''''

Real-time solver using Runge Kutta method is currently implemented as an extern method for initial testing purpose.
Building a stand alone real-time solver is already in progress.

Using real-time data reader, one can calculate dCoffee/dt for cooling of coffee example. From initial test, I have collected following logs
Source:[http://ascendcode.cheme.cmu.edu/viewvc.cgi/code/branches/dipak/models/dipak/Workspace_Broken/sensorreadings.logs <font color="orange">dipak</font>:models/dipak/Workspace_Broken/sensorreadings.logs]

If we calculate dCoffee/dt we can get a graph as shown in following diagram

<div class="thumb tnone"><div class="thumbinner" style="width:602px;">[[Image:DTCoffee.png]] <div class="thumbcaption"><div class="magnify">[[File:DTCoffee.png|<img src="/skins/common/images/magnify-clip.png" width="15" height="11" alt="" />]]</div>Rate of change of coffee temperature with reference to environment temperature.</div></div></div>

Todo: Application: Once we have dCoffee/dt, we can solve '''model''' like following

<source lang="a4c">Qdot = h A (T_coffee - T_amb)

Qdot = - m_coffee * cp_coffee * dT_coffee / dt

where Qdot is the heat transfer rate
h is the convection coefficient
A is the heat transfer surface area
T_coffee and T_amb are the coffee (+ cup) and ambient air temperatures, respectively.

m_coffee is the mass of the coffee + cup
cp_coffee is the average specific heat capacity of the cup + coffee etc</source>
<br />
Following graph shows simulated results from real-time solver Vs real-reading over 10 mins of time slot.

Source can be found at: Source:[http://ascendcode.cheme.cmu.edu/viewvc.cgi/code/branches/dipak/models/dipak/RealtimeSolver <font color="orange">dipak</font>:models/dipak/RealtimeSolver]
<div class="thumb tnone"><div class="thumbinner" style="width:602px;">[[Image:RK_Solver.png]] <div class="thumbcaption"><div class="magnify">[[File:RK_Solver.png|<img src="/skins/common/images/magnify-clip.png" width="15" height="11" alt="" />]]</div>Simulated results after 1*10 steps vs real reading</div></div></div>

As you can see, prediction after 1st step starts differing than actual measured reading meaning we needed to tune the step to get accurate simulated results.

Main Page

2010-05-13T14:03:14Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

<div class="thumb tright"><div class="thumbinner" style="width:307px;">[[Image:Main-screenshot.png]] <div class="thumbcaption"><div class="magnify">[[File:Main-screenshot.png|<img src="/skins/common/images/magnify-clip.png" width="15" height="11" alt="" />]]</div>The main window of the [[PyGTK GUI]] for ASCEND. There are [[PyGTK_Screenshots|more screenshots]].</div></div></div>

ASCEND is an free open-source software program for solving small to very large mathematical models. ASCEND can solve systems of non-linear equations, linear and nonlinear optimisation problems, and dynamic systems expressed in the form of differential/algebraic equations.

There is an '''[[ASCEND_overview|ASCEND Overview]]''' with more information about ASCEND capabilities. Alternatively, you can look at some [[PyGTK_Screenshots|screenshots]] or some [[Worked_examples|example problems]] solved using ASCEND.

<div style="width: 36em; padding-top:8px;padding-bottom:12px; border:solid 2pt gray;background-color:#ffff88;margin-top:5px;margin-bottom:5px;padding:8px">'''Current version 0.9.7''': [http://sourceforge.net/project/platformdownload.php?group_id=167528 Download] (Windows, Linux, Mac)<br /><small>Please read the [[Quick_Start|Installation notes]]!</small></div>
<font color="red">'''News flash:'''</font> ASCEND has been accepted into [http://socghop.appspot.com/ Google Summer of Code 2010]! Students who have applied should 'watch' [[GSOC2010|our GSOC2010 page]].

== In this wiki... ==

* some new [[Category:Documentation|user's documentation]] (in progress)
* some information on the various ASCEND [[solvers]].
* the [[Worked examples]] and the [[ModelLibrary]] for some examples of what you can do with ASCEND.
* information on [[Building ASCEND]] from the source code
* information about extending ASCEND using [[external libraries]].
* read about current [[Development activities]].
* the [[Developer%27s_Manual|Developer's Manual]] in progress.
* some ideas for [[Student Projects]] working on ASCEND.
* please '''[[Debugging_ASCEND|report a bug]]''' if you find one.

This [http://en.wikipedia.org/wiki/Wiki wiki] is open to contributions from anyone. All we ask is that you [[Special:UserLogin|register]] with your email address. Note that there is some earlier content from our [http://ascend.cheme.cmu.edu/ascend_about.htm previous website] gradually being migrated to this wiki.

== Get the source code ==

Source code (as well as binary) releases are available from our [http://sourceforge.net/projects/ascend-sim/files/ download page] on SourceForge.

Open access to our [[VersionManagement|subversion repository]] is available, or you can [http://ascendcode.cheme.cmu.edu/ browse our code online].

== Send us your ASCEND models ==

We are working on expanding our [[ASCEND Model Library]]. If you have used ASCEND to solve a relatively common problem, your model will probably be of use to other users. Please contact [[Art Westerberg]] or one of the other developers if you are interested in sharing any models that you might have developed.

Thin-walled tank/Arrays

2010-05-13T14:03:05Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

<div style="float:right;width:33ex;padding-left:3px;margin-left:10px;margin-bottom:10px;border:solid 2pt grey;background-color: #eee">
'''Thin-walled tank tutorial'''
<br /><small>[[Thin-walled_tank|←Return to start]]</small>

* [[Thin-walled_tank/Introduction|Introduction]]
* [[Thin-walled_tank/Adding_methods_to_a_model|Adding methods to a model]]
* <strong class="selflink">Arrays</strong>
* [[Thin-walled_tank/Building_complex_models|Building complex models]]
* [[Thin-walled_tank/Parameterized_models|Parameterised models]]

See also [[Category:Tutorials|Other tutorials]]
</div>

== Introduction ==

See also [[Arrays and sets]].

Often we want to write a model containing the same type of part repeatedly. We introduce arrays along with the ability to write loops to allow us to write the model code one time, where we index the code over the elements.

Also we often wish to characterize an entity built out of an arbitrary number of repeating units. For example, a hotel chain might wish to design a type of hotel building whose number of floors and number of units on each floor is arbitrary - within limits - but whose guest rooms are the same for all instances of this type of building. The model would be an array of rooms over an array of floors. When using arrays in such a hotel model, we can reference the bottom floor, the top floor, or any floor whose index we can relate to bottom and top - such as the floor at or near the middle - floor (N+1)/2 - without knowing a priori the actual number of floors. The modeler's intention could be to code the model, debug that code with different test values for the number of floors and rooms, and then make this model available for others to use.

In ASCEND, we can have arrays of variables and, as with this hotel example, we can have arrays of instances of complex things. We can have an array of arrays of arrays (of arrays of arrays).

It should be noted that a spreadsheet program is fine for handling arrays with known fixed dimension. However, a spreadsheet program is not well suited to handle arrays of arbitrary dimension. We would have to write macros to generate the actual arrays within the spreadsheet once we have decided on the size of the array - something most of us would not be skilled at doing.

== A collection of thin-walled tank farms ==

Okay, we have to stretch a bit to come up with a model based on our thin-walled tank, but modeling a collection of thin-walled tank farms might be one way to have such a need. We are a company that intends to build tank farms in several key locations throughout the country. Each farm will have several tanks located at it, and we wish to compute the total metal mass in each location as well as the total overall metal mass.

We shall create our model using the thin_walled_tank model of the previous section. We first model a tank farm. Following our earlier approach, we shall write and debug this model before using it as a part of our larger model. Thus we include a method that can set up a test case for it.

<source lang="a4c">MODEL tank_farm;

NT IS_A integer_constant;

metal_density IS_A mass_density;
metal_mass_farm IS_A mass;

tank[1..NT] IS_A partitioned_thin_walled_tank;

metal_density, tank[1..NT].metal_density ARE_THE_SAME;

(* an alternate way to write the above two lines of code would be

FOR i IN [1..NT] CREATE
tank[i] IS_A partitioned_thin_walled_tank;
metal_density, tank[i].metal_density ARE_THE_SAME;
END FOR;
*)

massFarm: metal_mass_farm = SUM[tank[1..NT].metal_mass];

METHODS

METHOD specify;
FOR i IN [1..NT] DO

RUN tank[i].specify;
END FOR;
END specify;

END tank_farm;

MODEL test_tank_farm;
tankFarm IS_A tank_farm;

tankFarm.NT :== 3;

METHODS

METHOD values;

tankFarm.metal_density := 7.85 {g/cm^3};
tankFarm.tank[1].side.D := 5 {m};

tankFarm.tank[2].side.D := 6 {m};

tankFarm.tank[3].side.D := 7 {m};

tankFarm.tank[1..3].side.H := 6 {m};

tankFarm.tank[1..3].wall_thickness := 1.5 {cm};

END values;
METHOD specify;
RUN tankFarm.tank[1..3].specify;

END specify;

END test_tank_farm;</source>

We now model the collection of tank farms specific to our company.

<source lang="a4c">MODEL our_tank_farms;

locations IS_A set OF symbol_constant;

locations :== ['SanFrancisco','St Louis','Pittsburgh'];

total_mass_all_farms IS_A mass;

(* set up tank farms *)
tankfarm[locations] IS_A tank_farm;
tankfarm['SanFrancisco'].NT :== 2;

tankfarm['St Louis'].NT :== 4;
tankfarm['Pittsburgh'].NT :== 1;

(* equations *)

massAllFarms: total_mass_all_farms = SUM[tankfarm[locations].metal_mass_farm];

METHODS

METHOD specify;
FOR i IN [locations] DO

RUN tankfarm[i].specify;
END FOR;
END specify;

METHOD valuesSF;
tankfarm['SanFrancisco'].metal_density := 7.85 {g/cm^3};

tankfarm['SanFrancisco'].tank[1].side.D := 4.5 {m};

tankfarm['SanFrancisco'].tank[2].side.D := 3 {m};

tankfarm['SanFrancisco'].tank[1..2].side.H := 6 {m};

tankfarm['SanFrancisco'].tank[1..2].wall_thickness := 1.5 {cm};

END valuesSF;

METHOD valuesSTL;
tankfarm['St Louis'].metal_density := 7.85 {g/cm^3};

tankfarm['St Louis'].tank[1].side.D := 4 {m};

tankfarm['St Louis'].tank[2].side.D := 4 {m};

tankfarm['St Louis'].tank[3].side.D := 5 {m};

tankfarm['St Louis'].tank[4].side.D := 5 {m};

tankfarm['St Louis'].tank[1..2].side.H := 6 {m};

tankfarm['St Louis'].tank[3..4].side.H := 7 {m};

tankfarm['St Louis'].tank[1..4].wall_thickness := 1.7 {cm};

END valuesSTL;

METHOD valuesPIT;
tankfarm['Pittsburgh'].metal_density := 7.85 {g/cm^3};

tankfarm['Pittsburgh'].tank[1].side.D := 8 {m};

tankfarm['Pittsburgh'].tank[1].side.H := 10 {m};

tankfarm['Pittsburgh'].tank[1].wall_thickness := 1.85 {cm};

END valuesPIT;

METHOD values;
RUN valuesSF;

RUN valuesSTL;
RUN valuesPIT;
END values;

METHOD setup;
RUN specify;
RUN values;

END setup;

END our_tank_farms;</source>

We have put these two models together in a file called twt0420.a4c, Adding in the appropriate INCLUDE statements completes the tank farm model file, which you can test using ASCEND.

==Things to observe from this example==

There are a few things we should observe about this example. For more details on all this, see the [http://ascend.cheme.cmu.edu/ftp/pdfSyntax/new_syntax_body.pdf syntax document for ASCEND] and the wiki page on [[Arrays_and_sets| arrays and sets]].

# We indexed the tanks within each farm using integer constants (i.e., of type integer_constant). We indexed our tank farms using symbol constants. Both are legal as indices for arrays.
# We can indicate indices as constants (e.g., 1 or 'Pittsburgh') or for integer constants as ranges (e.g., 1..NT). Not illustrated is that one can select among array elements with a list, too (e.g., 1..2, 4)
# We actually set up an interesting two dimensional array in this example. The first (think of it as being the rows of the array) index is for the tank farms; the second (think of this as being the columns) is over the tanks in each farm. The number of tanks varies from farm to farm so the array is not rectangular.
# We reference a row/column element as tank_farm['St Louis'].tank[2]. Note how clear this reference is; we do not need to wonder what the first index in an array is over - it is over tank farms.

==And other things to know about set handling in ASCEND==

# ASCEND lets you also do some pretty fancy set manipulation, such as forming the UNION, INTERSECTION and DIFFERENCE to form sets as combinations of other sets.
<br />
Continue with [[Thin-walled_tank/Parameterized_models|the last section, Parameterised models]]

[[Category:Examples]]
[[Category:Tutorials]]

History of ASCEND

2010-05-13T14:02:56Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

ASCEND is an acronym which stands for Advanced System for Computations in ENgineering Design. The name ASCEND first appeared in print in 1978. The ASCEND programs are a series of modeling systems that Arthur Westerberg and his graduate students at Carnegie Mellon University have developed since that time.

===ASCEND I===

Dean Benjamin developed the first ASCEND system. It was an interactive system in Fortran. Chemical engineering students at Carnegie Mellon University used this system from about 1978 to 1982 to carry out multicomponent flash calculations. It supported the senior design project.

===ASCEND II===

Almost in parallel, Michael Locke developed the ASCEND II simulation system for his PhD thesis [1981]. ASCEND II allowed users to create models by configuring them using predefined types of parts. System maintainers defined the library of types, each in the form of seven handcrafted Fortran subroutines. These routines computed the space needed for the data when instancing a part, generated numerical values for the partial derivatives and the residuals of the equations that the part instance provided to the overall model, generated proper variable and equation scaling and the like. Michael Locke used this system to create models involving a few thousand equations to test variants of the Sequential Quadratic Programming algorithm. Tom Berna and he developed for optimizing structured engineering systems. Selahattin Kuru also used ASCEND II to generate and test solution algorithms for dynamic simulation that he subsequently developed for his PhD. Two companies used the software architectural design of ASCEND II to create their own internal equation-based modeling systems.
Experience at this time demonstrated that models involving several thousands of equations were solvable and could even be efficiently optimized. The question of interest moved from how to solve large equation-based models to how to aid an engineer to pose them, debug them and get them to solve.

In 1983 Dean Benjamin proposed the first version of a modeling language for posing complex models. Larry Gaydos and Art Westerberg further developed this language in the spring of 1984.

===ASCEND III===

In 1984 Peter Piela undertook a PhD project with Art Westerberg to “reduce the time needed to create and solve a complex model by one order of magnitude.” He developed what became ASCEND III. He had the help of two Carnegie Mellon University undergraduate students, Tom Epperly and Karl Westerberg, and of Roy McKelvey, a member of the faculty in the Design Department in Fine Arts. This team developed this system on the Apollo workstation and in Pascal. It comprised three parts: a modeling language and compiler, an interactive user interface and a suite of solvers. The language used object-oriented principles, with the exception of hiding of information. Modelers define types to create model definitions. A type (called a model in ASCEND) is a collection of variables and complex parts whose types are previously defined and the definition of the equations that model is to supply. A model can also be the refinement of a previously defined type. The language fully supported associative arrays and sets. For example, a distillation column is an array of trays. It also supported deferred binding by allowing one to reach inside a part and alter one of its parts to be a more refined type. The language and its compiler obviated the need to have a system programmer write the seven subroutines needed in ASCEND II.
The interactive user interface supplied the user with organized access to the many tools in the ASCEND III system. There were tools to load model definitions, to compile them, to browse them, to solve them, to probe them, to manipulate the display units (e.g., ft/s) for reporting variable values, to create reports and to run methods on them. One could even point at a part and ask that it be made into a more refined type (triggering the compiler to restart). As previously solved values were not overwritten, they became the starting point for the more complex model. Thus one could creep up on the solution by solving more and more complex versions of a model. Many of the tools were there specifically to aid the user in debugging their models as they tried to solve them. A tool could tell a user that the model appeared to be singular and why. Another set of tools aided in picking a consistent set of variables to fix before solving. Browsing allowed the user to look at all parts of the model. It was easy to check the configuration of a model. One could ask that parts of a model be solved one at a time.

Experience by Peter Piela, Oliver Smith, Neil Carlberg and Art Westerberg with ASCEND III demonstrated very clearly that skilled modelers could develop, debug and solve very complex models much more rapidly than they could with previously available tools, easily meeting the original target of a order of magnitude reduction in time required.

===ASCEND IIIc===

In the fall of 1992, Kirk Abbott and Ben Allan approached Art Westerberg and said they wanted to convert the ASCEND III system from Pascal into C. They would also use Tcl/Tk for the interface. With these changes, the system would then run on most Unix workstations. Tom Epperly and Karl Westerberg had already created a C version for the compiler and solver. Abbott and Allan wanted to do this conversion even after they were warned that converting the system would take time that they could be using to do more apparently relevant work to complete their PhD theses. They insisted. They were aided by Tom Epperly who, although located remotely, worked with them on the compiler. In eight months and putting in excessively long hours, they had a working system that could could mimic most of the capabilities of the ASCEND III system.

Several students and a few people outside CMU could now use the system for modeling. Bob Huss and Boyd Safrit performed the hardest testing when they used ASCEND IIIc to model nonideal distillation processes. They developed and solved models involving up to 15,000 equations. Using a rudimentary capability for solving initial value problems, Safrit also solved dynamic models. With use came the recognition of a need for improvements.

Attempts to teach ASCEND to others showed that it was a great system to speed up the modeling process for experts. Nonexperts found it nearly impossible to reuse models contained in the ASCEND libraries. The library for computing the thermodynamic properties of mixtures was particularly elegant but almost impossible to reuse. Modelers would reinvent their own properties models quickly, unable to use the library models.

Models larger than about 17,000 equations took more space than our largest workstation could provide. The models by Huss and Safrit were pushing the limits. Abbott and Allan established the goal to increase the size possible by a factor of at least ten, i.e., to about a quarter of a million equations. ASCEND needed to solve models more quickly. Without counting the increases coming from faster and larger hardware, the goal here too was a factor of ten. If solving were to be that fast, then compiling would stand out as unacceptably slow. The goal: ten times faster.

Abbott, with Allan, exposed a new style for modeling in ASCEND. He created prototypes of the various repeating types that occur in a model. The compiled equations and other data structures to define these prototypes then became available for all subsequent instances of parts that were of the same type as the prototype. Only the instance data needed to be developed separately. Demonstrated impact on compile times was dramatic.

Abbott, with Allan, looked at how to speed up the solving times. The new twist was to use the model structure as defined by the model definition to expose a global reordering for the model equations before presenting them for solution. The time to solve the linear Newton equations as the inner loop of solving nonlinear equations dropped by factors of 5 to 10.

===ASCEND IV===

Ben Allan took a lead role and worked with Mark Thomas, Vicente Rico-Ramirez and Ken Tyner to produce the next version of ASCEND, ASCEND IV. Playing the role of tester, an undergraduate, Jennifer Perry, demonstrated that Allan’s introduction of parameterized types dramatically increased the reusability of the model libraries, converting it into an almost automatable exercise. Adding language constructs to permit the modeler to state what constitutes misuse of a model leads to the system generating diagnostics the model itself defines. Allan also completely revised the data structures and the interface between ASCEND and its solvers so that adding new solvers is much less work and so the solvers in ASCEND themselves become separable from ASCEND and usable by others.

Allan also defined the addition of NOTES to ASCEND, which are like methods except they are not understood by the ASCEND system itself. Rather they can be passed to programs outside ASCEND. An example includes documentation notes which a documentation manager can use to compose answers to queries about what is in an ASCEND model. Another is a note that contains a bitmap description of a part that an external package could use to draw a symbol of that part.

ASCEND IV can now handle discrete variables and constants (logical, binary, symbolic, and integer). It supports the solver directing that parts of the model be excluded when solving such as when solving using implicit enumeration (dynamic model modification). CONOPT is now attached for optimization.

===ASCEND IV, post 2004===

Art Westerberg retired from Carnegie Mellon University in 2004. While still leading this project, he is also in charge of maintaining the ASCEND server that resides at CMU. This server hosts this wiki and our subversion repository, as well as our web pages. He also continues in his role as resident expert in the design and use of ASCEND.

Our work is less formal now as it no longer involves active research projects at CMU. However, we now have an active set of volunteers participating in the project.

John Pye is a Research Fellow at the Australian National University. He has submitted a PhD on the topic of system modeling of a solar thermal energy system and continues to work in modeling and optimisation of solar energy systems. He has contributed a new ASCEND GUI and Python bindings as well as several new solvers.

Benjamin Allan now resides in California and continues to be reponsible for the code and the current TclTk API of ASCEND.

Krishnan Chittur is a professor at the University of Alamaba in Hunstville with wide-ranging interests in the field of chemical engineering, bioengineering and biomaterials. He uses ASCEND in his undergraduate teaching programs and believes that it has great value in exposing students to numerical modeling issues enabling solution of complex systems, while at the same time permitting detailed understand of the way that such tools work. He contributes to the examples in ASCEND.

The active project participants tap several of those mentioned above who continue to have an interest in ASCEND and to participate when requested as resident experts to the code and modeling examples.

[[Category:Documentation]]

SELECT

2010-05-13T14:02:44Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

The '''SELECT''' statement is used to selectively compile equations according to the value of constants in the model. This similar to the [[WHEN]] statement used in [[Conditional modelling]], except that it allows no possibility of equations being switched on or off after the model is instantiated.

Be careful when naming your equations inside a SELECT statement: A name cannot be defined two different ways inside the SELECT statement, but it may be defined outside the case statement and then ''refined'' in different ways in separate cases, using [[IS_REFINED_TO]].

This statement is declarative. Order of the CASEs does not matter. All matching cases are executed. The OTHERWISE is executed if present and no other CASEs match. SELECT is not
allowed inside [[FOR]], but writing [[FOR]] statements inside SELECT is allowed.

<source lang="a4c">MODEL eos_constants (

component_name WILL_BE symbol_constant;
);
T_c IS_A temperature_constant;
p_c IS_A pressure_constant;

(* depending on the value of the 'component_name' parameter, set the
critical temperature and pressure to the appropriate value. *)
SELECT(component_name)
CASE 'hydrogen':

T_c :== 33 {K};
p_c :== 12.9 {bar};

CASE 'water':
T_c :== 647.3 {K};
p_c :== 221.2 {bar};

CASE 'oxygen':
T_c :== 154.6 {K};
p_c :== 50.4 {bar};

OTHERWISE:
T_c :== -1 {K};
p_c :== -1 {Pa};

END SELECT;
END eos_constants;</source>

In fact, this is the technique used in the current {{src|models/components.a4l}} model in our [[ModelLibrary]].

See also [[Conditional modelling]].

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

Category:Syntax

2010-05-13T14:02:34Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

This category contains pages that describe the ASCEND modelling language syntax. [[Category:Documentation|More general documentation]] is also available.

<div id="mw-pages">
<h2>Pages in category "Syntax"</h2>

The following 55 pages are in this category, out of 55 total.

{| class="wikitable"
|-
|
<h3>A</h3>

* [[ALIASES]]
* [[ARE ALIKE]]
* [[ARE THE SAME]]
* [[ATOM]]
* [[Abs]]
* [[Arrays and sets]]
<h3>C</h3>

* [[CALL]]
* [[CASE]]
* [[CONDITIONAL]]
* [[Conditional modelling]]
<h3>D</h3>

* [[DATA]]
* [[DECREASING]]
* [[Dynamic modelling]]
<h3>E</h3>

* [[EXTERNAL]]
<h3>F</h3>

* [[FALSE]]
* [[FIX]]
* [[FOR]]
* [[FREE]]
|
<h3>I</h3>

* [[IF]]
* [[IMPORT]]
* [[IS A]]
* [[IS REFINED TO]]
<h3>L</h3>

* [[Ln]]
* [[Log10]]
* [[Lower bound]]
<h3>M</h3>

* [[MAX]]
* [[MAXIMIZE]]
* [[METHODS]]
* [[MIN]]
* [[MINIMIZE]]
* [[MODEL]]
<h3>N</h3>

* [[NOTES]]
<h3>O</h3>

* [[OTHERWISE]]
* [[Object-oriented modelling]]
* [[Optimisation]]
<h3>P</h3>

* [[PROVIDE]]
* [[PROVIDES]]
|
<h3>R</h3>

* [[REFINES]]
* [[REQUIRE]]
* [[RUN]]
<h3>S</h3>

* [[SATISFIED]]
* [[SELECT]]
* [[SUM]]
* [[SWITCH]]
* [[Solver var]]
<h3>T</h3>

* [[TRUE]]
<h3>U</h3>

* [[USE]]
* [[Upper bound]]
<h3>W</h3>

* [[WHEN]]
* [[WHERE]]
* [[WHILE]]
* [[WILL BE]]
* [[WILL BE THE SAME]]
* [[WILL NOT BE THE SAME]]
* [[WITH VALUE]]
|}
</div>
[[Category:Documentation]]

User:DanteStroe

2010-05-13T14:02:26Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

'''Dante Stroe'''

Proposal: [http://socghop.appspot.com/student_project/show/google/gsoc2009/ascend/t124021684017]

Mentor: [[Ben Allan]].

Subversion branch: [http://ascendcode.cheme.cmu.edu/viewvc.cgi/code/branches/dante/ <font color="orange">dante</font>:]

== Detailed plan ==
===By mid-term review:===
* 18/06/2009
* Completed the parser modifications s.t. ASCEND now understands "LINK('key',a,b)" syntax, where 'key' is the key that links identifies the set of instances "a" and "b" inside the the link table. The test model z-link.a4l has also been modified.
* Added a Link table object (struct link_table_t) to the model instance type that will store the aforementioned links. The link table is in fact a "gl_list" where each entry in the list represents a pointer to a "LINK" entry that is currently defined in the following way:<source lang="a4c">/**
* DS: Entry in the Link table (which is in fact a list) associated with each model

* instantiator.
*/
struct link_entry_t {

union {

struct Statement * statptr; /* pointer to the declarative statement */
struct VariableList * vl; /* used if the we use the GUI to LINK, otherwise NULL */

} u;
struct gl_list_t *instances_cache; /**< (cache) pointer to the list of instances that are linked*/

symchar* key_cache; /**< key that defines the linked instances */
unsigned long length; /**< Number of instances in the linked_instances list. */

unsigned long capacity; /**< Capacity of the link entry, in terms of the number of the instances that can be linked. */
unsigned int flags; /**< Status flags.used to differentiate between LINK statements in the declarative part(FIXED) and the ones in the methods (not fied). */

}</source>
* This is defined as part of the TypeDescription class. where the "link_table" is declared as an attribute as part of the ModelArgs union element of the TypeDescription:<source lang="a4c">struct ModelArgs {
struct gl_list_t *link_table; /**< pointer to the table of "LINK" relationships of the model*/

....</source>
===Instantiation and LINK statements===
* Additions to the "instantiate" class can be followed at [http://ascendcode.cheme.cmu.edu/viewvc.cgi/code/branches/dante/ascend/compiler/instantiate.c?sortby=date&r1=2394&r2=2296&pathrev=2394 this rev diff]
* In order for LINK statements to have consistent instances in the ENTRIES, they have to be instantiate only after all the models, relations, logical statements and "when" statements have been instantiated. (Otherwise we run the risk of having the Link statements invalid after the instantiation a re-instantiation procedures are carried on).
** Compiler initially had 5 instantiation/re-instantiation phases, and now it has 6 :
*** 1. Models (instantiate models and disregard any other type of statements)
*** 2. Relations (instantiate "relations" and disregard any other type of statements)
*** 3. Logical Statements (instantiate logicals and disregard any other type of statements)
*** 4. When Statements (instantiate "when"s and disregard any other type of statements)
*** 5. LINK Statements (instantiate LINKS and disregard any other type of statements) - Added
*** 6. default (visit instance tree once more and if it is the case warn about any un-executed statements).
*** 1. Models (instantiate models and disregard any other type of statements)
*** 2. Relations (instantiate "relations" and disregard any other type of statements)
*** 3. Logical Statements (instantiate logicals and disregard any other type of statements)
*** 4. When Statements (instantiate "when"s and disregard any other type of statements)
*** 5. LINK Statements (instantiate LINKS and disregard any other type of statements) - Added
*** 6. default (visit instance tree once more and if it is the case warn about any un-executed statements).
** 1. Models (instantiate models and disregard any other type of statements)
** 2. Relations (instantiate "relations" and disregard any other type of statements)
** 3. Logical Statements (instantiate logicals and disregard any other type of statements)
** 4. When Statements (instantiate "when"s and disregard any other type of statements)
** 5. LINK Statements (instantiate LINKS and disregard any other type of statements) - Added
** 6. default (visit instance tree once more and if it is the case warn about any un-executed statements).
** Compiler initially had 5 instantiation/re-instantiation phases, and now it has 6 :
*** 1. Models (instantiate models and disregard any other type of statements)
*** 2. Relations (instantiate "relations" and disregard any other type of statements)
*** 3. Logical Statements (instantiate logicals and disregard any other type of statements)
*** 4. When Statements (instantiate "when"s and disregard any other type of statements)
*** 5. LINK Statements (instantiate LINKS and disregard any other type of statements) - Added
*** 6. default (visit instance tree once more and if it is the case warn about any un-executed statements).
*** 1. Models (instantiate models and disregard any other type of statements)
*** 2. Relations (instantiate "relations" and disregard any other type of statements)
*** 3. Logical Statements (instantiate logicals and disregard any other type of statements)
*** 4. When Statements (instantiate "when"s and disregard any other type of statements)
*** 5. LINK Statements (instantiate LINKS and disregard any other type of statements) - Added
*** 6. default (visit instance tree once more and if it is the case warn about any un-executed statements).
** 1. Models (instantiate models and disregard any other type of statements)
** 2. Relations (instantiate "relations" and disregard any other type of statements)
** 3. Logical Statements (instantiate logicals and disregard any other type of statements)
** 4. When Statements (instantiate "when"s and disregard any other type of statements)
** 5. LINK Statements (instantiate LINKS and disregard any other type of statements) - Added
** 6. default (visit instance tree once more and if it is the case warn about any un-executed statements).
* Compiler initially had 5 instantiation/re-instantiation phases, and now it has 6 :
** 1. Models (instantiate models and disregard any other type of statements)
** 2. Relations (instantiate "relations" and disregard any other type of statements)
** 3. Logical Statements (instantiate logicals and disregard any other type of statements)
** 4. When Statements (instantiate "when"s and disregard any other type of statements)
** 5. LINK Statements (instantiate LINKS and disregard any other type of statements) - Added
** 6. default (visit instance tree once more and if it is the case warn about any un-executed statements).
** 1. Models (instantiate models and disregard any other type of statements)
** 2. Relations (instantiate "relations" and disregard any other type of statements)
** 3. Logical Statements (instantiate logicals and disregard any other type of statements)
** 4. When Statements (instantiate "when"s and disregard any other type of statements)
** 5. LINK Statements (instantiate LINKS and disregard any other type of statements) - Added
** 6. default (visit instance tree once more and if it is the case warn about any un-executed statements).
* 1. Models (instantiate models and disregard any other type of statements)
* 2. Relations (instantiate "relations" and disregard any other type of statements)
* 3. Logical Statements (instantiate logicals and disregard any other type of statements)
* 4. When Statements (instantiate "when"s and disregard any other type of statements)
* 5. LINK Statements (instantiate LINKS and disregard any other type of statements) - Added
* 6. default (visit instance tree once more and if it is the case warn about any un-executed statements).
<br />
For the purpose of adding this new "LINK" phase in the instantiation procedure the following functions were added. They were implemented and documented in a similar fashion (if the case) with respect to the other instantiation functions:

* These functions set the bits such that the following functions only execute the LINK statements, as well as the FORs and select(re-evaluate) statements that contain LINKs.
<source lang="a4c">void Pass5SetLinkBits(struct Instance *inst)</source>
<source lang="a4c">struct Instance *Pass5InstantiateModel(struct Instance *result, unsigned long *pcount)</source>
<br />

* By now the pass5pendings was already set by silent visit to the instance tree. (which means we updated the pending instances from the last phase)
<source lang="a4c">void Pass5ProcessPendingInstances(void)</source>
<br />

* Try to execute all the LINK statements in instance work. It assumes that work is the top of the pending instance list. Will skip all non-LINK statements. (Note: Only models get here)
<source lang="a4c">static void Pass5ExecuteLinkStatements(struct BitList *blist, struct Instance *work, int *changed)</source>
<br />

* Statement processing. We are processing just the LINK statements that are stand-alone as well as the ones inside FORs (That's what we should be left with anyway, since this is the last phase of instantiation). This Executes each LINK with "ExecuteLNK(instance,statement)" function and each FOR that contains a LINK with "Pass5ExecuteFOR(instance,statement)" (this only executes the LINKs inside the FOR)
<source lang="a4c">static int Pass5ExecuteStatement(struct Instance *inst,struct Statement *statement)</source>
<br />

* This is where all the sanity checks are done for the LINK statement and parameters correctness aw well as the addLinkEntry function is called for the given model.
<source lang="a4c">int ExecuteLNK(struct Instance *inst, struct Statement *statement)</source>

* Near future tasks:
** Implement the rest of functions present at [http://ascendwiki.cheme.cmu.edu/LINK_semantics]
** Unit testing of the all the functions implemented
** At this point ascend should be able compile models with "LINK" syntax and store it
** Regression testing and making sure committed code is properly documented
** Implement the rest of functions present at [http://ascendwiki.cheme.cmu.edu/LINK_semantics]
** Unit testing of the all the functions implemented
** At this point ascend should be able compile models with "LINK" syntax and store it
** Regression testing and making sure committed code is properly documented
* Implement the rest of functions present at [http://ascendwiki.cheme.cmu.edu/LINK_semantics]
* Unit testing of the all the functions implemented
* At this point ascend should be able compile models with "LINK" syntax and store it
* Regression testing and making sure committed code is properly documented

===By final review:===

* Initial value modeling
** Modify the DAE solver implementation to make use of the newly implemented "LINK" relationship, however in the form of DERIV(dx_dt,x) . (Note: this implies that "t" is declared as the independent variable in use beforehand, and the compiler should know this until instructed otherwise). This relation would inherit/extend the LINK relationship. See [[Improved DAE syntax]].
** Add functionality to relation classes, to make use of the Link information present for given instances in the case of derivatives. Need
** Testing and documentation
** Modify the DAE solver implementation to make use of the newly implemented "LINK" relationship, however in the form of DERIV(dx_dt,x) . (Note: this implies that "t" is declared as the independent variable in use beforehand, and the compiler should know this until instructed otherwise). This relation would inherit/extend the LINK relationship. See [[Improved DAE syntax]].
** Add functionality to relation classes, to make use of the Link information present for given instances in the case of derivatives. Need
** Testing and documentation
* Modify the DAE solver implementation to make use of the newly implemented "LINK" relationship, however in the form of DERIV(dx_dt,x) . (Note: this implies that "t" is declared as the independent variable in use beforehand, and the compiler should know this until instructed otherwise). This relation would inherit/extend the LINK relationship. See [[Improved DAE syntax]].
* Add functionality to relation classes, to make use of the Link information present for given instances in the case of derivatives. Need
* Testing and documentation

* Update on completed tasks:
** Finished and corrected implementation of testing suite for the LINK syntax (in general) : {{srcbranch|dante|models/test/z-link.a4c}}. The file also contains some fail cases and a special LINK type with key 'testSuite' that runs a procedure to test the functions described in [http://ascendwiki.cheme.cmu.edu/LINK_semantics LINK]
** Created 'ode' type LINKS that are defined by the 'ode' key and a list of instances out of which, currently, the last one is the independent variable, whereas the rest are the differential variable in decreasing order. Ex:
** Finished and corrected implementation of testing suite for the LINK syntax (in general) : {{srcbranch|dante|models/test/z-link.a4c}}. The file also contains some fail cases and a special LINK type with key 'testSuite' that runs a procedure to test the functions described in [http://ascendwiki.cheme.cmu.edu/LINK_semantics LINK]
** Created 'ode' type LINKS that are defined by the 'ode' key and a list of instances out of which, currently, the last one is the independent variable, whereas the rest are the differential variable in decreasing order. Ex:
* Finished and corrected implementation of testing suite for the LINK syntax (in general) : {{srcbranch|dante|models/test/z-link.a4c}}. The file also contains some fail cases and a special LINK type with key 'testSuite' that runs a procedure to test the functions described in [http://ascendwiki.cheme.cmu.edu/LINK_semantics LINK]
* Created 'ode' type LINKS that are defined by the 'ode' key and a list of instances out of which, currently, the last one is the independent variable, whereas the rest are the differential variable in decreasing order. Ex:
<source lang="a4c">LINK('ode',dx_dt,x,t);</source>

** The derivative chains declared in LINK can be arbitrarily long, however the solver does not handle more than 2nd order derivatives
** The "ode" LINKS can be declared in both the declarative and procedural part of the model.
** If multiple derivative chains are declared, they must all have the same independent variable, otherwise the user is prompted with an error message.
** The LINKs don't make use of the .ode_type/ode_id attributes of the instances, but rather, the LINK structure. This implies that if one variable is present in two or more derivative chains, there is no longer the need to declare additional variables.
*** The implementation was done in "ascend/ascend/system/analyze.c" for the solver and "ascend/ascend/integrator/integrator.c" for the integrator. For this purpose the follwing external functions were implemented in "\ascend\ascend\compiler\link.c":
*** The implementation was done in "ascend/ascend/system/analyze.c" for the solver and "ascend/ascend/integrator/integrator.c" for the integrator. For this purpose the follwing external functions were implemented in "\ascend\ascend\compiler\link.c":
** The implementation was done in "ascend/ascend/system/analyze.c" for the solver and "ascend/ascend/integrator/integrator.c" for the integrator. For this purpose the follwing external functions were implemented in "\ascend\ascend\compiler\link.c":
** The derivative chains declared in LINK can be arbitrarily long, however the solver does not handle more than 2nd order derivatives
** The "ode" LINKS can be declared in both the declarative and procedural part of the model.
** If multiple derivative chains are declared, they must all have the same independent variable, otherwise the user is prompted with an error message.
** The LINKs don't make use of the .ode_type/ode_id attributes of the instances, but rather, the LINK structure. This implies that if one variable is present in two or more derivative chains, there is no longer the need to declare additional variables.
*** The implementation was done in "ascend/ascend/system/analyze.c" for the solver and "ascend/ascend/integrator/integrator.c" for the integrator. For this purpose the follwing external functions were implemented in "\ascend\ascend\compiler\link.c":
*** The implementation was done in "ascend/ascend/system/analyze.c" for the solver and "ascend/ascend/integrator/integrator.c" for the integrator. For this purpose the follwing external functions were implemented in "\ascend\ascend\compiler\link.c":
** The implementation was done in "ascend/ascend/system/analyze.c" for the solver and "ascend/ascend/integrator/integrator.c" for the integrator. For this purpose the follwing external functions were implemented in "\ascend\ascend\compiler\link.c":
* The derivative chains declared in LINK can be arbitrarily long, however the solver does not handle more than 2nd order derivatives
* The "ode" LINKS can be declared in both the declarative and procedural part of the model.
* If multiple derivative chains are declared, they must all have the same independent variable, otherwise the user is prompted with an error message.
* The LINKs don't make use of the .ode_type/ode_id attributes of the instances, but rather, the LINK structure. This implies that if one variable is present in two or more derivative chains, there is no longer the need to declare additional variables.
** The implementation was done in "ascend/ascend/system/analyze.c" for the solver and "ascend/ascend/integrator/integrator.c" for the integrator. For this purpose the follwing external functions were implemented in "\ascend\ascend\compiler\link.c":
** The implementation was done in "ascend/ascend/system/analyze.c" for the solver and "ascend/ascend/integrator/integrator.c" for the integrator. For this purpose the follwing external functions were implemented in "\ascend\ascend\compiler\link.c":
* The implementation was done in "ascend/ascend/system/analyze.c" for the solver and "ascend/ascend/integrator/integrator.c" for the integrator. For this purpose the follwing external functions were implemented in "\ascend\ascend\compiler\link.c":
<source lang="a4c">extern int getOdeId(struct Instance *model,struct Instance *inst);</source>
<source lang="a4c">extern int getOdeType(struct Instance *model,struct Instance *inst);</source>

The functions return the ode_type and ode_id (as in prev syntax) of a given variable in a model from the LINK table structures, if the variable pertains to any derivative chains.

* In order to test this syntax the following models were added to the repository (modified from previous models with derivative chains):
** {{srcbranch|dante|models/test/ida/singlederiv_wLINK.a4c}}
** {{srcbranch|dante|models/test/ida/twoderiv_wLINK.a4c}}
** {{srcbranch|dante|models/dyn_tank_wLINK.a4c}}
** {{srcbranch|dante|models/johnpye/pendulum_wLINK.a4c}}
** {{srcbranch|dante|models/test/dopri5/dopri5test_wLINK.a4c}}
** {{srcbranch|dante|models/test/ida/singlederiv_wLINK.a4c}}
** {{srcbranch|dante|models/test/ida/twoderiv_wLINK.a4c}}
** {{srcbranch|dante|models/dyn_tank_wLINK.a4c}}
** {{srcbranch|dante|models/johnpye/pendulum_wLINK.a4c}}
** {{srcbranch|dante|models/test/dopri5/dopri5test_wLINK.a4c}}
* {{srcbranch|dante|models/test/ida/singlederiv_wLINK.a4c}}
* {{srcbranch|dante|models/test/ida/twoderiv_wLINK.a4c}}
* {{srcbranch|dante|models/dyn_tank_wLINK.a4c}}
* {{srcbranch|dante|models/johnpye/pendulum_wLINK.a4c}}
* {{srcbranch|dante|models/test/dopri5/dopri5test_wLINK.a4c}}

* The following model is not yet functional, due to the fact that the instances that are vector elements inside LINKs, which are inside a "FOR", are not properly evaluated. (currently working on that):
** {{srcbranch|dante|models/test/dopri5/aren.a4c}}
** {{srcbranch|dante|models/test/dopri5/aren.a4c}}
* {{srcbranch|dante|models/test/dopri5/aren.a4c}}

* Other feasible targets this week:
** Implement "INDEPENDENT t" type syntax for the independent variable of the derivative chains, with the restriction of having only a single declaration of this type in a model. This implies that the independent variable will no longer have to be declared inside the 'ode'-type LINKs. This would be implemented by using the LINK structure as well.
** Replace the "LINK('ode',dx_dt,x)" type of syntax, with DER(dx_dt,x).(To be agreed if this is smth desirable or LINK is enough for now)
** update: since the [http://ascendcode.cheme.cmu.edu/viewvc.cgi?view=rev&revision=2570 latest commit] the following block of code:
** Implement "INDEPENDENT t" type syntax for the independent variable of the derivative chains, with the restriction of having only a single declaration of this type in a model. This implies that the independent variable will no longer have to be declared inside the 'ode'-type LINKs. This would be implemented by using the LINK structure as well.
** Replace the "LINK('ode',dx_dt,x)" type of syntax, with DER(dx_dt,x).(To be agreed if this is smth desirable or LINK is enough for now)
** update: since the [http://ascendcode.cheme.cmu.edu/viewvc.cgi?view=rev&revision=2570 latest commit] the following block of code:
* Implement "INDEPENDENT t" type syntax for the independent variable of the derivative chains, with the restriction of having only a single declaration of this type in a model. This implies that the independent variable will no longer have to be declared inside the 'ode'-type LINKs. This would be implemented by using the LINK structure as well.
* Replace the "LINK('ode',dx_dt,x)" type of syntax, with DER(dx_dt,x).(To be agreed if this is smth desirable or LINK is enough for now)
* update: since the [http://ascendcode.cheme.cmu.edu/viewvc.cgi?view=rev&revision=2570 latest commit] the following block of code:
<source lang="a4c">LINK('ode',dx_dt,x,t);</source>
<source lang="a4c">DER(dx_dt,x);
INDEPENDENT t;</source>

* either of the two new statements can be declared in any order and in any part of the model as with LINK; The example models have also been updated with the new syntax.

[[Category:GSOC2009]]
[[Category:ASCEND_Contributors]]

Category:Outdated

2010-05-13T14:02:14Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

Articles in need of an update...

<div id="mw-pages">
<h2>Pages in category "Outdated"</h2>

The following 18 pages are in this category, out of 18 total.

{| class="wikitable"
|-
|
<h3>A</h3>

* [[ASCEND capabilities]]
<h3>B</h3>

* [[Building a Debian package]]
<h3>C</h3>

* [[ComponentizingAscend]]
<h3>D</h3>

* [[Debugging ASCEND]]
<h3>I</h3>

* [[IPOPT]]
* [[Initial-value modelling]]
|
<h3>I cont.</h3>

* [[Installing LyX]]
<h3>N</h3>

* [[New Compiler]]
* [[Notes Ubuntu 7.04 Install]]
* [[Notes Ubuntu 7.10 Install]]
<h3>P</h3>

* [[Prerequisites for Windows]]
* [[PythonWrapper]]
<h3>R</h3>

* [[Regression Testing]]
|
<h3>R cont.</h3>

* [[Running the Python/PyGTK GUI on Windows]]
<h3>S</h3>

* [[Sensitivity study]]
* [[Steam properties]]
* [[Supporting RPMs]]
<h3>T</h3>

* [[TclTk Quick Guide]]
|}
</div>

Saving and restoring model state

2010-05-13T14:02:05Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

{{task}}

This task is related to the task of creating a [[canvas-based modeller for ASCEND]], because we would like for canvas-based models to be saved including their current solved state. This will make them more useful for review by other users, and for referring back to the solution of a previous study-case.

'''The current status of this work''' is that Arijit implemented a [[Saving_and_restoring_model_state#Current_method_of_implementation|Python-based way]] of saving the model state; we would like to think about other more portable approaches though.

<br />
Requirements for saving and restoring model state:

* must store all non-constant values defined in the model
* this include booleans, integers, symbols and reals.
* includes not just solver_var's but also attributes of variables, such as lower_bound and upper_bound
* note that attributes are not hard-wired into ASCEND but are defined on the fly in .a4c and .a4l files.
* should not make use of solvers_var_list etc, because we want our saved state to be solver-agnostic.
* should be possible to save state of a whole model or any sub-tree (starting from a certain instance and working down)
* must be able to deal with arrays, whens, conditionals, etc.
* need to identify what should be done in the case of 'sets'.
* need to avoid storing multiple copies of 'cliqued' variables (ARE_THE_SAME, ALIASES).

Suggestions:

* should be implemented at the libascend C level, so that it can be readily be used by across all GUIs if desired
* would replace the current hybrid Tcl+C apporach (producing .a4v files)
* needs to be interfaced with Python in a way that the resulting return value can be pickled and unpickled efficiently.
* suggested Python datatype is the 'dict'
* some care required when dealing with type conversions between Python and C and vice versa.
* suggest a new SWIG object being the 'CachedValue' or similar, able to hold bool, int, real, string (and set?) values.

More detailed design should be discussed and more specific design worked out here.

Note current partial functionality implemented in {{src|ascend/compiler/instance_io.c}} (a 'restore' function was never implemented).

Note current Tcl/Tk GUI functionality implemented in {{src|tcltk/interface/BrowserProc.c}} and {{src|tcltk/tk/BrowserProc.tcl}}. This approach generates the stored file using C code, then utilised the Tcl interpreter to act as a parser for the stored file when reading it back (see Brow_parse_values).

== Possible solutions ==

=== Opaque object ===

Functions could be written that would create an opaque object via SWIG that would do the job of serialising and unserialising values from the instance hierarchy. The opaque object could be interfaced with the 'copy_reg' module or augmented with __setstate__ and __getstate__ functions to allow the object model state object to be saved in a pickle.

=== Python-to-C flat data conversion ===

This approach would serialise an instance sub-tree into a set of key-value pairs which could then be exchanged easily both to and from Python. A problem might be the 'heaviness' of the storage format (a lot of space consumed storing strings like 'lower_bound', 'upper_bound', and perhaps a lot more processor-intensive. Some care required with data types -- eg converting from PyObject to string/int/real/bool as required for the Instance type. But relatively easy to implement.

=== Python-to-C tree conversion ===

As above, but return a hierarchical dict.

=== Pure Python implementation ===

Is it possible to iterate through the tree in Python and produce something workable that's reasonably fast?

=== Wrapping the old Tcl functionality ===

The old Tcl/C code uses C code to traverse the model tree and output a text file containing essentially a Tcl script that, when run, does the job of reinserting values into the instance tree by looking up identifiers one-by-one using the 'qlfdid' routines. This approach to restoring model values is possibly not particular efficient, but does currently work. The hazards of using the Tcl interpreter from within Python are a bit scary, however, and it would be nicer to keep language 'cleanness' in the Python code.

== Per-solver solutions? ==

Different solvers work in different ways. All ASCEND solvers work off the 'solver lists' that contain the 'flat' form of an ASCEND model including real-valued variables and real-valued relations, boolean-valued vars and rels, WHENs, etc. Instead of solving values from the instance tree, an alternative approach would be to save the contents of the solver lists.

One problem with this approach is that it could make it harder to restore model state for modified models -- what would happen if a variable had been added to or removed from the model?

This approach would however make saving and loading quite a bit easier: all the problems of cliques are eliminated, and there is no need to recursively descend into a tree structure -- everything's flat.

== Current method of implementation ==

Currently, the Canvas Modeler employs Python based way of saving canvas data. When the canvasmodel is solved, it stores the values of all the variables present in the canvasmodel, supplied by the <simulation>.getallVariables() function, into a dictionary named 'saved_data' belonging to the BlockCanvas class. The code which does this in present in the method 'run_canvas' of 'blocklist.py'. It is where the 'saved_data' dictionary gets populated. This is then pickled upon saving of the canvasmodel. Thats how the data gets stored.

Next, comes the retrieval of data upon loading of canvas pickle files, which is carried out in the following manner. First of all, loading of canvas pickle files is performed by the 'fileopen' method of 'blocklist.py', which upon successful retrieval of pickled data, calls another method 'load_presaved_canvas', again belonging to 'blocklist.py'. This method 'load_presaved_canvas' then instantiates the canvasmodel. It then retrieves the values from the 'saved_data' dictionary and assigns them to the variables of instantiated canvasmodel. That is how data is retrieved back from the canvas pickle file.

[[Category:Proposed]]

ASCEND overview

2010-05-13T14:01:55Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

ASCEND is a system for '''solving systems of equations''', aimed at engineers and scientists. It allows you to '''build up complex models''' as as systems constructed from simpler '''sub-models'''. Using ASCEND it is simple to '''play around''' with your model, examine its behaviour, and work out how it can best be solved. You can '''easily change which variables are fixed''' and which are to be solved, and you can examine the way in which the model is being solved.

After looking through this brief introduction to what ASCEND is all about, you might want to look at the [[ASCEND history]], a more detailed list of [[ASCEND capabilities]], see some [[worked examples]], find out about [[ASCEND_Users_and_Friends|the developers]] or look at more detailed [[Category:Documentation|documentation]].

== Example of a simple model in ASCEND ==

In ASCEND, models are written in a special-purpose modelling language that combines declarative ''variables'' and ''equations'' with procedural ''methods''. The following simple method calculates the mass of water in a tank:

<source lang="a4c">REQUIRE "atoms.a4l";

MODEL tank;
V IS_A volume;
A IS_A area;

h IS_A distance;
d IS_A distance;
area_eqn: A = 1{PI} * d^2 / 4.;

vol_eqn: V = A * h;
rho IS_A mass_density;

m IS_A mass;
mass_eqn: m = rho*V;

METHODS
METHOD on_load;
FIX d, h, rho;

d := 50 {cm};
h := 90 {cm};

rho := 1000 {kg/m^3};
END on_load;
END tank;</source>

This model declares variables and equations in the 'main' part of the model. Then, in a method called 'on_load', the model specifies that the variables <tt>d</tt>, <tt>h</tt> and <tt>rho</tt> will be 'fixed', and provides their values.

This model can be loaded into ASCEND, usually just by double-clicking the file, then solved by hitting the 'solve' button, with the following result:

[[Image:simple-tank-example.png]]

This is a very simple model: there is much more that ASCEND can do. For example, '''without editing the above model file''', one can use the GUI to 'fix' the volume and diameter of the tank and solve instead for the height, with just a couple of clicks, then resolve for a new tank volume of 200 L:

[[Image:simple-tank2.png]]

For models like this, ASCEND can quickly show you how it's solving the equation, using a simple graph representation:

[[Image:solve-order.png]]

Simple models like this can be useful and quite efficient ways to inspect the behaviour of simple systems of equations. They can also be useful as quick 'calculators': they can be loaded, the known variables typed in, and the solved results quickly seen.

ASCEND provides a way to keep tables of 'observed' values and plot relationships between variables:

[[Image:observer.png]][[Image:observer-plot.png]]

Note that ASCEND is dealing with [[units of measurement]] clearly and transparently. In ASCEND you never have to worry about 'getting the units right' because it understands how to convert between different units like in, ft, cm, m, km for length and L, m³ etc for volume.

To learn more about the ASCEND modelling language and how it can be used to build up models, see the [[Thin Walled Tank]] tutorial.

== More complex models ==

Simple models like this are useful, but serious problems, especially in process engineering and mechanical engineering often involve more complex interactions, often with multiple subsystems, interconnected parts, and so on. In this case, ASCEND provides a number of [[object-oriented modelling]] capabilities, allowing more complicated models to be declared, such as this simple steam power station (Rankine cycle) simulation:

<source lang="a4c">REQUIRE "johnpye/rankine.a4c";
MODEL power_station;

(* sub-models *)
BO IS_A boiler_simple;
TU IS_A turbine_simple;

CO IS_A condenser_simple;
PU IS_A pump_simple;

(* variable 'alias' for convenience *)

mdot ALIASES TU.mdot;

(* connections *)
BO.outlet, TU.inlet ARE_THE_SAME;

TU.outlet, CO.inlet ARE_THE_SAME;
CO.outlet, PU.inlet ARE_THE_SAME;

PU.outlet, BO.inlet ARE_THE_SAME;

(* overall cycle efficiency *)
eta IS_A fraction;

eta * (BO.Qdot_fuel - PU.Wdot) = TU.Wdot;

METHODS
METHOD specify;
RUN ClearAll;
FIX PU.outlet.p, BO.outlet.T, PU.inlet.p, PU.inlet.h, TU.eta, PU.eta, BO.eta, mdot;

END specify;
METHOD values;
mdot := 900 {t/d};

PU.outlet.p := 2000 {psi};
BO.outlet.T := 1460 {R}; BO.outlet.h := 3400 {kJ/kg};

PU.inlet.p := 1 {psi}; PU.inlet.h := 69.73 {btu/lbm};

TU.eta := 1.0; PU.eta := 1.0; BO.eta := 1.0;

END values;
METHOD on_load;
RUN specify;
RUN values;

END on_load;
END power_station;</source>

This model makes use of several sub-parts such as 'pump_simple' and so on, which are defined in another file called 'rankine.a4c' pointed to via the [[REQUIRE]] statement. More documentation [[Category:Syntax|about the syntax]] is available.

Using this style of modular model, it is possible to build and test simple component models, then 'wire them up' into more complex models. This is something that is very difficult to do with standard spreadsheet models as commonly used by engineers. With a library of standard component models at your disposal, you can get working sooner on the complex problems which you have before you.

See [[Object-oriented modelling]] for a summary of language features that help in writing more complex models. You might also be interested in our thoughts about [[Modelling with Spreadsheets]].

== Solvers and integrators ==

The basic engineering calculation being represented in the above examples is a simple "solve for 'x'" type of problem, for which ASCEND uses its [[QRSlv]] solver. For these problems ASCEND orders the equations, then uses [http://en.wikipedia.org/wiki/Newton%27s_method Newton's method] to iteratively solve any sets of simultaneous equations present in the system. However not all engineering problems are like this. Other types of problems can also be solved using ASCEND:

* [[Optimisation|Optimisation problems]], where an objective value must be minimised by varying a set of input variables (see [[CONOPT]], [[IPOPT]])
* [[ODE]] and [[DAE]] problems, where the behaviour of a time-varying system is to be studied (see [[LSODE]], [[IDA]])
* [[Conditional_modelling|Conditional models]], where the applicable equations depend on the value or values of other variables in the model (see [[CMSlv]])

The ASCEND GUI allows you to load a model then select a suitable 'solver' or 'integrator' according to the type of problem that you have. Several solvers are already included with ASCEND, and the API allows you to write new solvers without having to dig into the innards of ASCEND.

ASCEND can show you the model structure as 'viewed' by the solver. For example, using [[QRSlv]], the simple Rankine-cycle model has the following lower-triangular [[incidence matrix]] structure, which indicates that no iterative solving is needed:

[[Image:rankine-incidence.png]]

See [[Solvers]] and [[Dynamic modelling]] for more information.

== Thermodynamics ==

An area where process engineers often run into difficulty with modelling is in incorporating the thermodynamic properties of fluids in their models. ASCEND provides some simple thermodynamics capabilities, which have proven sufficient for modelling distillation and flash problems in chemical engineering, and also integrates with high-accuracy IAPWS-IF97 steam tables for use in power engineering applications.

See [[Thermodynamics with ASCEND]], [[FPROPS]] and [[Steam properties]] for more information.

== Extending ASCEND ==

ASCEND can be extended in a number of ways, using [[external libraries]]. These are pieces of code that ASCEND loads on request. They can be:

* [[External Methods]], doing procedural stuff to models
* [[external relations]], adding new equations to the model, such as complex thermodynamic property relationships
* [[External Solvers]], that solve a model, according to the programmer's definition of 'solve' :-)
* [[external Integrators]], that integrate a model (ie solve for the dynamic response of a system; solve an inital value problem)

External libraries are normally written in C/C++, but we have implemented support for also writing external methods using Python.

== Scripting and automation ==

ASCEND exposes its user interface at several different levels: C, C++ and Python. Usefully, this means that if you have a more complicated modelling problem than can be solved with the ASCEND GUI, you can write a Python script that loads your model and solves it in various ways: effectively you can 'drive' ASCEND however you want, automatically.

See [[Scripting ASCEND using Python]].

== Development of ASCEND ==

ASCEND does enough things to be genuinely useful for engineers, students and scientists, and has an active user group. It was first written around 1978, and has been through several re-writes over that time. Its 'compiler' (which converts the input file into a tree structure containing variables, submodels, and equations) as well as its solvers have been the subject of several PhDs and many features in ASCEND have since been incorporated into commercial simulation programs. Development of ASCEND continues in exciting new directions however. We are working on adding new solvers as well as improving ASCEND's support for solving ODEs and DAEs.

If you are interested in contributing to ASCEND, please see our [[Development Activities]] page and also our list of [[Student Projects]]. We have been accepted to participate in the the 2009Google Summer of Code, so you might even be able to get paid!

[[Category:Documentation]]

Category:Documentation

2010-05-13T14:01:46Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

If you are new to ASCEND, '''it is recommended that you start with the [[ASCEND overview]]''', then try working through the new '''[[Intro_to_ASCEND_-_thin_walled_tank|tutorial]]''', which introduces the ASCEND modelling language.

More detailed documentation is available from the '''<a href="/images/6/61/Book.pdf" class="internal" title="Book.pdf">ASCEND Manual (1.3 MB .pdf)</a>''', but note that it largely refers to the older Tcl/Tk-based GUI, and the recommended GUI is the newer PyGTK-based GUI.

If you need help getting ASCEND running on your machine, please check the '''[[Quick Start]] guide'''.

'''[[Category:Development|Developer documentation]]''' exists under a separate top-level category heading.

See also

* [http://ascend.cheme.cmu.edu/pdfhelp.htm Older versions] of the documentation
* [http://ascend.cheme.cmu.edu/ascend_bibliography.htm ASCEND bibliography]
* [[History of ASCEND]]
<div id="mw-subcategories">
<h2>Subcategories</h2>

This category has the following 6 subcategories, out of 6 total.
<h3>E</h3>

* [[Category:Examples|Examples]]
* [[Category:Experimental|Experimental]]
* [[Category:Extending_ASCEND|Extending ASCEND]]<h3>S</h3>

* [[Category:Solvers|Solvers]]
* [[Category:Syntax|Syntax]]<h3>T</h3>

* [[Category:Tutorials|Tutorials]]
</div><div id="mw-pages">
<h2>Pages in category "Documentation"</h2>

The following 92 pages are in this category, out of 92 total.

{| class="wikitable"
|-
|
<h3>A</h3>

* [[ALIASES]]
* [[ARE ALIKE]]
* [[ARE THE SAME]]
* [[ASCEND Model Library]]
* [[ASCEND capabilities]]
* [[ASCEND overview]]
* [[Arrays and sets]]
<h3>B</h3>

* [[Boundary detection]]
* [[Building ASCEND]]
<h3>C</h3>

* [[Calculation of sun position]]
* [[Checking models]]
* [[Conditional modelling]]
* [[Create with understanding]]
<h3>D</h3>

* [[DATA]]
* [[Damped response]]
* [[Diagnose tool]]
* [[Documentation systems]]
* [[Dynamic modelling]]
<h3>E</h3>

* [[EXTERNAL]]
* [[Environment variables for ASCEND]]
* [[EnzymeKinetics]]
* [[Equation]]
* [[External libraries]]
* [[External relations]]
<h3>F</h3>

* [[FIX]]
* [[FOR]]
* [[FPROPS]]
* [[FREE]]
* [[Freesteam]]
<h3>G</h3>

* [[Goal seeking solver]]
|
<h3>H</h3>

* [[History of ASCEND]]
* [[How do I fix my model]]
* [[HydroSim]]
<h3>I</h3>

* [[IDA]]
* [[IMPORT]]
* [[IPOPT]]
* [[IS A]]
* [[IS REFINED TO]]
* [[Incidence Graph]]
* [[Incidence matrix]]
* [[Instance hierarchy]]
<h3>M</h3>

* [[MAXIMIZE]]
* [[METHODS]]
* [[MINIMIZE]]
* [[MODEL]]
* [[Model self-testing]]
* [[ModellingTechniques]]
* [[More documentation]]
<h3>N</h3>

* [[NOTES]]
<h3>O</h3>

* [[Object-oriented modelling]]
* [[Observers]]
* [[Optimisation]]
* [[Other modelling tools]]
<h3>P</h3>

* [[PROVIDE]]
* [[Parametric studies]]
* [[Plotting in ASCEND]]
* [[Prerequisites for Linux]]
* [[Prerequisites for Windows]]
* [[PyGTK GUI command-line parameters]]
* [[PyGTK Quick Guide]]
* [[PyGTK Screenshots]]
|
<h3>P cont.</h3>

* [[PythonWrapper]]
<h3>Q</h3>

* [[Quick Start]]
<h3>R</h3>

* [[REQUIRE]]
* [[Referenced examples]]
* [[Running the Python/PyGTK GUI on Windows]]
<h3>S</h3>

* [[SELECT]]
* [[Scaling]]
* [[Scripting ASCEND using Python]]
* [[Sensitivity study]]
* [[Solver NOTES]]
* [[Structured models]]
* [[Supporting RPMs]]
* [[Syntax highlighting]]
<h3>T</h3>

* [[TclTk screenshots]]
* [[Thermodynamics with ASCEND]]
<h3>U</h3>

* [[UNIFAC model]]
* [[Units of measurement]]
* [[Useful resources]]
<h3>V</h3>

* [[VLEWhy]]
* [[Vapor-liquid equilibrium]]
* [[Variable]]
* [[Vleexample]]
<h3>W</h3>

* [[WHEN]]
* [[WHERE]]
* [[WHILE]]
* [[WILL BE]]
* [[WILL BE THE SAME]]
* [[What if I do not have CONOPT]]
* [[Worked examples]]
* [[Writing ASCEND external relations in C]]
<h3>X</h3>

* [[Xgraph]]
|}
</div><div id="mw-category-media">
<h2>Media in category "Documentation"</h2>

The following 3 files are in this category, out of 3 total.

{| class="wikitable"
|-
| <div class="gallerybox" style="width: 155px;">
<div class="thumb" style="padding: 13px 0; width: 150px;"><div style="margin-left: auto; margin-right: auto; width: 120px;">[[Image:Book.pdf]]</div></div>
<div class="gallerytext">
[[File:Book.pdf|Book.pdf]]<br />
1,344,205 bytes<br />
</div>
</div>| <div class="gallerybox" style="width: 155px;">
<div class="thumb" style="padding: 13px 0; width: 150px;"><div style="margin-left: auto; margin-right: auto; width: 120px;">[[Image:DifferentialAlgebraicEqn.pdf]]</div></div>
<div class="gallerytext">
[[File:DifferentialAlgebraicEqn.pdf|DifferentialAlgebrai...]]<br />
50,241 bytes<br />
</div>
</div>| <div class="gallerybox" style="width: 155px;">
<div class="thumb" style="padding: 13px 0; width: 150px;"><div style="margin-left: auto; margin-right: auto; width: 120px;">[[Image:Howto_thermo.pdf]]</div></div>
<div class="gallerytext">
[[File:Howto_thermo.pdf|Howto thermo.pdf]]<br />
197,576 bytes<br />
</div>
</div>|}
</div>

Thermodynamics with ASCEND

2010-05-13T14:01:37Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

The ASCEND [[ModelLibrary]] includes a range of models for dealing with chemical and physical properties of materials, phase equilibrium, and reaction kinetics.

We have a brief 'HOW TO' guide for doing thermodynamics calculations with ASCEND, thanks for [http://pedro.valelima.com/phd/ Pedro Vale Lima], here: <a href="/images/9/97/Howto_thermo.pdf" class="internal" title="Howto thermo.pdf">Media:howto_thermo.pdf</a>. The following text is our partial (ongoing) transcription of that document into wikitext.

In addition to the methods described in this page, there are other ways of calculating thermodynamic properties using ASCEND. See [[FPROPS]] and [[freesteam]] for example.

You can access the models from the HOW TO in the [[ModelLibrary]] as {{src|models/thermodynamics_example.a4c}}.

== Physical property data ==
Physical property data from the book Reid, Prausnitz & Polling, ''The Properties of Gases and Liquids'', 4th Ed.,McGraw-Hill, 1987, are included in the ASCEND model file {{src|models/components.a4l}}.

To add support for a new fluid component, it is suggested that you create your own copy of that file, and add some new code. First add your component to the <tt>supported_components</tt> list:
<source lang="a4c">supported_components :== [
'hydrogen'
,'carbon_dioxide'
,(* add another one here *)
];</source>
Then, add a CASE in the [[SWITCH]] statement to define the constants for your particular substance:
<source lang="a4c">CASE 'my_new_substance':
rpp_index :== 111;

(* add your data here... *)</source>
Here is the meaning of the constants that are used in the components models:

{| class="wikitable"
|-
! constant ! meaning
|-
| rpp_index | Index in the Reid et al book

|-
| formula | Chemical formula (optional, informational only)
|-
| subgroups | Component subgroups for the [[UNIFAC model]].
|-
| wilson_set | Wilson groups for the [[Wilson liquid model]].

|-
| mw | Molecular weight
|-
| Tb | Boiling-point temperature (at what pressure??)
|-
| Tc | Temperature at critical point

|-
| Pc | Pressure at critical point
|-
| Vc | (Molar?) volume at critical point
|-
| Zc | Compressibility factor at critical point.

|-
| omega | Pitzer acentric factor
|-
| cpvap''a..d'' | Constants for vapour-phase <span class="texhtml">''c''<sub>''p''</sub></span> calculation.<br /><span class="texhtml">''c''<sub>''p''</sub> = ''a'' + ''b''''T'' + ''c''''T''<sup>2</sup> + ''d''''T''<sup>3</sup></span>
|-
| Hf | Enthalpy of formation
|-
| Gf | Gibbs free energy of formation
|-
| vp''a..d'' | Constants for vapour pressure calculation (three equations can be used)

|-
| vp_correlation | Number that represents which correlation is used for calculation of vapour pressure
|-
| Hv | Enthalpy of vapourisation
|-
| lden | Liquid density

|-
| Tliq | Temperature at which the liquid density (lden) is specified.
|}
Finally, add the name of your new component in the check list of <tt>components</tt> model:
<source lang="a4c">FOR i IN components DO

ASSERT (i IN ['hydrogen', 'carbon_dioxide' (* others here *)) == TRUE;

END FOR;</source>

== Calculating properties for a single component ==

The simples state to model is the one that represents a single component in a single phase. To elaborate this model, one needs an [http://en.wikipedia.org/wiki/Equation_of_state equation of state] (EOS). As there is no universal equation of state, the thermodynamic libraries in ASCEND contain several models, and leave the decision about which one to use up to the user.

The ASCEND thermodynamics library has two models for vapour components ('''<tt>ideal_vapour_component</tt>''' and '''<tt>Pitzer_vapor_component</tt>''') and one model for liquid components ('''<tt>Rackett_liquid_component</tt>'''). All these models are similar in concept; only the EOS changes. We'll use the ideal vapour model to illustrate the main concepts.

The model defines the equations needed to calculate the molar volume <math>{\bar v}</math>, enthalpy <math>{\bar h}</math> and Gibbs free energy <math>{\bar g}</math>, based on the temperature <span class="texhtml">''T''</span>, pressure <span class="texhtml">''p''</span> and component properties.

The first equation needed by the ideal gas model is the well known equation of state,

:<math>p{\bar v}={\bar R}T</math>

where <math>{\bar R}</math> is the ideal gas constant. To define <math>{\bar h}</math>, one can use the constant-pressure molar heat capacity, <math>{\bar c}_p</math>. The heat capacity is define implicitly as a polynomial function of temperature:

:<math>{\bar c}_p = a + b T + c T^2 + d T^3</math>

where ''a'', ''b'', ''c'', and ''d'' are defined (as <tt>cpvap''a..d''</tt>) in the components data file. Remembering that, for an ideal gas, <math>{\bar h}</math> is defined as

:<math>{\bar h} - {\bar h}_0 = \int_{T_0}^{T} {\bar c}_p dT</math>

results in the following explicit equation for <math>{\bar h}</math>:

:<math>{\bar h} = {\bar h}_0 + a (T-T_0) + \frac{1}{2}{b (T^2 - T_0^2)} + \frac{1}{3}c (T^3 - T_0^3) + \frac{1}{4}d (T^4 - T_0^4)</math>

Note that, if it were ''not'' an ideal gas, <math>{\bar h}</math> would also depend on <span class="texhtml">''p''</span>. Looking back again to your old thermodynamics textbook, it can then be proven that

:<math>d ( \frac{\bar g}{{\bar R}T} ) = \frac{\bar v}{{\bar R}T} dp - \frac{\bar h}{{\bar R}T^2}dT</math>

Substitution of equations 1 and 4 on equation 5 followed by equation yields an equation for <math>{\bar g}</math> with the form

:<math>\bar g = {\bar g}(p,T)</math>

As a summary, this model has three equations (eqs 1, 4, 6), and five variables (<span class="texhtml">''p''</span>, ''T'', <math>\bar g</math>, <math>\bar h</math>, <math>\bar v</math>).

=== ASCEND implementation ===

In the thermodynamics library, we see the above code defined as follows:

<source lang="a4c">MODEL ideal_vapor_component(
P WILL_BE pressure;

T WILL_BE temperature;
data WILL_BE td_component_constants;
) REFINES pure_component;

(*... *)
END ideal_vapor_component;</source>

=== Using the ASCEND single-component model ===

The [[Object-oriented_modelling|parametric model declaration]] above tells you that if you want to instantiate an 'ideal_vapor_component', then you need to first declare variables for pressure 'P' and temperature 'T', as well as the thermodynamic data 'data'. Hence, we can create out little model for evaluating these properties as follows:

<source lang="a4c">(* Simple example for vapour properties of water from ideal gas equation *)
REQUIRE "thermodynamics.a4l";
REQUIRE "johnpye/thermo_types.a4c";

MODEL my_props;
p IS_A pressure;
T IS_A temperature;

cd IS_A components_data(['water'],'water');
props IS_A ideal_vapor_component(p,T,cd.data['water']);

v_m ALIASES props.v;
v IS_A specific_volume;
v = Vm / props.data.mw;

rho IS_A mass_density;
rho = 1./v;
h_m ALIASES props.h;

METHODS
METHOD on_load;
RUN props.default_all;
RUN props.specify;

p := 1 {atm};
T := 400 {K};

END on_load;
END my_props;</source>

Using this model, ASCEND returns a calculated value of the mass-density of steam at 400 K and 1 bar as 0.54892 kg/m³. Calculation using the IAPWS-IF97 steam correlations (using [[freesteam]] via Python, specifically) gives me 0.54758 kg/m³, so the difference between the ideal gas calculation and the more rigorous correlation is not that great in this case.

Note that this model also calculates the molar Gibbs free energy and molar enthalpy for the single component.

We can now use this model to solve a simple example problem:

=== Example 1 ===

'''Find the change in enthalpy for water that is heated from 125 °C to 225 °C at constant pressure of 1 bar.'''

A model that performs this calculation is shown here:

<source lang="a4c">(* model to calculate change in enthalpy from 125°C to 225 °C at 1 bar. *)
MODEL example_1;

A, B IS_A my_props;
A.p, B.p ARE_THE_SAME;

dh_m IS_A molar_energy;
dh_m = B.h_m - A.h_m;

dh IS_A specific_enthalpy;
dh = dh_m / A.props.data.mw;

METHODS
METHOD on_load;
RUN A.on_load;
RUN B.on_load;

A.T := 273.15 {K} + 125 {K};

B.T := 273.15 {K} + 225 {K};

END on_load;
END example_1;</source>

This model gives the result that the change in molar enthalpy <math>\Delta {\bar h}</math> (which in the model we call 'dh_m') is equal to 3.4902 kJ/kmol. And we calculate the change in specific enthalpy <span class="texhtml">Δ''h''</span> to be 193.74 kJ/kg. This value compares fairly well with values from steam tables: for this process, Heywood gives <span class="texhtml">Δ''h''</span> = 199 kJ/kg, so the error is ~3%.

The standard model for liquid components in ASCEND ('''<tt>Rackett_liquid_component</tt>''') has one slight difference from the vapour model present. As the enthalpy and free energy depend on knowledge of the vapor pressure, there is an additional equation with the correlation to calculate this value. You still have two degrees of freedom, but now you have six variables and four equations.

=== Example 2 ===

'''Calculate the temperature at which the vapour pressure for water is 1 atm.'''

To solve this problem, we start with the first model that was used here, but modify it to use the Rackett liquid component model instead.

<source lang="a4c">(* model to calculate temperature at which vapour pressure of water is 1 atm *)
MODEL example_2;

p IS_A pressure;
T IS_A temperature;
cd IS_A components_data(['water'],'water');

props IS_A Rackett_liquid_component(p,T,cd.data['water']);

v_m ALIASES props.v;
v IS_A specific_volume;

v = v_m / props.data.mw;
rho IS_A mass_density;

rho = 1./v;

p_vap ALIASES props.VP;

METHODS
METHOD on_load;
RUN props.default_all;
RUN props.specify;

p := 1 {atm};

(* reconfigure the program to solve with fixed VP and free T... *)
FREE T;

FIX p_vap;
p_vap := 1 {atm};

END on_load;

END example_2;</source>

Solving this model gives the result that <span class="texhtml">''T''</span> = 373.14 K, which is close enough (0.014 K) to the expected value of 100 °C or 273.15 K.

== Mixtures ==

As with the model for single components, the model for mixtures attempts to represent the mixture molar volume, enthalpy, and Gibbs free energy.

To understand this model, we present an example. Suppose you have a mixture of two components and want to calculate the molar volume. For each component you first calculate the molar volume for each pure species <math>{\bar v}_i^p</math>, where <span class="texhtml">''i''</span> is the index for the component, and <span class="texhtml">''p''</span> signifies 'pure'), using the models from the previous section. Then you calculate the molar volume for the species ''in the mixture'', <math>{\bar v}_i</math>, assuming some model for the mixing. At last, the molar volume is the sum of all species contributions weighted by the molar fraction of the species in the mixture.

For example, for an ideal gas mixture, we would have the following:

:<math>p {\bar v}_i^p = {\bar R} T</math>

:<math>{\bar v}_i = {\bar v}_i^p</math>

:<math>{\bar v} = \sum_i {y_i {\bar v}_i}</math>

The first equation comes from the <tt>ideal_vapor_component</tt> model (and there is one such equation for each component in the mixture). The second equation comes from the <tt>ideal_vapor_mixture</tt> model (again, one for each component). The last one is generic for all mixture models (and is part of the <tt>phase_partials</tt> model from which all mixture models are inherited).

The same concepts apply to enthalpy and Gibbs free energy. The equations for ideal vapour mixing and mixture calculation are the following:

:<math>p {\bar h}_i^p = {\bar h}_i^p</math>

:<math>{\bar h} = \sum_i {y_i {\bar h}_i}</math>

:<math>{\bar g}_i = {\bar g}_i^p + {\bar R} T \ln(y_i)</math>

:<math>{\bar g} = \sum_i {y_i {\bar g}_i}</math>

This model has one extra special equation whose meaning will be easier to understand after talking about phase equilibria:

:<span class="texhtml">
</span>

{| class="wikitable"
|-
| <span style="font-size: x-large; font-family: serif;">∑</span>| ''y''<sub>''i''</sub> + ''s'' = 1|-
| ''i''| |}

This equation introduces a new variable <span class="texhtml">''s''</span> called <tt>slack_PhaseDisappearance</tt>. With this formulation of the molar fraction sum, when <span class="texhtml">''s''</span> is fixed at 0, normal calculations are performed; when <span class="texhtml">''s''</span> is free, if the phase ceases to exist, <span class="texhtml">''s''</span> will be different from zero but simulation can continue. It's a clever and important trick for multi-phase equilibria. We will return to this issue later.

To review the variables and equations present in an idea gas mixture, note that for <span class="texhtml">''n''</span> components, we have <span class="texhtml">3''n''</span> ideal vapour component equations, and <span class="texhtml">3''n'' + 4</span> mixture equations. As far as variables, we have these values for the overall mixture: p, T, h, v, g,s ; then we have these values for each component: (FIXME).

Just a minor warning: when using models where <span class="texhtml">''n'' − 1</span> components are fixed, usually the un-fixed one is the 'reference component'. But be sure to check this and save yourself some trouble later. Let's see this mixture code in action now.

=== Example 3 ===

'''Calculate the change of enthalpy for a mixture of 60% water and 40% enthanol going from 400 to 500 K.'''

First look at the declaration of the '''<tt>ideal_vapor_mixture</tt>''' model to work out the necessary structure. Using that, we declare our model:

<source lang="a4c">MODEL water_and_ethanol;

cd IS_A components_data(['water','ethanol'], 'water');
props IS_A ideal_vapor_mixture(cd);

p ALIASES props.P;
T ALIASES props.T;

h_m ALIASES props.h_y;
METHODS
METHOD on_load;
RUN props.default_self;

RUN props.specify;
RUN props.values;
p := 1 {atm};

T := 400 {K};
props.y['ethanol'] := 0.4;

END on_load;
END water_and_ethanol;

MODEL example_3;
A, B IS_A water_and_ethanol;

dh_m IS_A molar_energy;
dh_m = B.h_m - A.h_m;

METHODS
METHOD on_load;
RUN A.on_load;
RUN B.on_load;

A.T := 400 {K};
B.T := 500 {K};

END on_load;
END example_3;</source>

This model gives us the result that <math>\Delta {\bar h}</math> is equal to 5.632 kJ/mol over that temperature increase.

<source lang="a4c">MODEL water_and_ethanol;
cd IS_A components_data(['water','ethanol'], 'water');

props IS_A Pitzer_vapor_mixture(cd);</source>

This gives us the slightly different result of <math>\Delta {\bar h}</math> = 5.724 kJ/mol.

=== Liquid mixtures ===

For mixtures involving liquids, ASCEND provides the [http://en.wikipedia.org/wiki/UNIFAC UNIFAC] mixture model, which is used together with the Rackett model for liquid properties. The number of equations in the UNIFAC model depends on the number of 'UNIFAC groups', <span class="texhtml">''l''</span>. For a mixture of <span class="texhtml">''n''</span> components, we end up with <span class="texhtml">9''n'' + 2''l'' + 4</span> equations and <span class="texhtml">10''n'' + 2''l'' + 6</span> variables, requiring us to fix <span class="texhtml">''n'' + 2</span> of those variables.

== Phase Equilibria ==

Phase equilibrium is provided by the final set of models in the ASCEND thermodynamics library. These types of models are the base for all sorts of chemical process models, starting from simple streams and working up to complex reaction and separation systems.

To model phase equilibria, one uses the '''<tt>thermodynamics</tt>''' model in the library. This model is the generic model for thermodynamics calculations, in that it can be used both for phase equilibria as well as for just single component properties or multi-phase mixtures. Of course, if you do choose to use the <tt>thermodynamics</tt> model for these simpler cases then you will be carrying around some unnecessary and redundant equations, but that's a price you might choose to pay for flexibility. The model has a generic interface and equilibrium relations that are only used for systems with at least two phases.

=== Generic interface ===

As mixtures are models that group simple components, phase equilibria groups the same mixture at different phases. By defining <span class="texhtml">γ<sup>''j''</sup></span> to be the molar fraction of phase <span class="texhtml">''j''</span> we have the usual fraction relation:

:<math>\sum_{i=1}^n{\gamma^j} = 1</math>

Now you must have another three equations to account for the phases:

:<math>{\bar v}^p = \sum_i{\gamma^i {\bar v}^i}</math>

:<math>{\bar h}^p = \sum_i{\gamma^i {\bar h}^i}</math>

:<math>{\bar g}^p = \sum_i{\gamma^i {\bar g}^i}</math>

where <math>{\bar v}^p</math>, <math>{\bar h}^p</math>, <math>{\bar g}^p</math> are the mixture properties defined by equations 8, 11 and 13 for each phase.

Another group of equations (one for each component) are needed to define a global fraction for a component.

:<math>y_i = \sum_p {\gamma^p y_i^p}</math>

=== Relative volatility model ===

This model has extra equations for multi-phase systems in equilibrium. The first group just equates pressures and temperature on all phases to the ones in the reference phase.

:<span class="texhtml">''p''<sup>''j''</sup> = ''p''<sup>ref</sup></span>

:<span class="texhtml">''T''<sup>''j''</sup> = ''T''<sup>ref</sup></span>

This accounts for <span class="texhtml">''m'' − 1</span> equations where <span class="texhtml">''m''</span> is the number of phases (the reference phase is excluded).

Now, recall the variable <span class="texhtml">''s''</span>, a.k.a. <tt>slack_PhaseDisappearance</tt>. There is one of these for each mixture. One problem with multiphase models is that models are written thinking of the existence of a phase, and if by some thermodynamics change the phase ceases to exist the equations become invalid. By using the following equation for each phase

:<span class="texhtml">''s''<sup>''j''</sup>γ<sup>''j''</sup> = 0</span>

It's possible for a phase to ''disappear''. If <span class="texhtml">γ<sup>''j''</sup></span> is not null, which means the phase exists, then <span class="texhtml">''s''<sup>''j''</sup></span> must be zero and by the already-presented relation <span class="texhtml">
</span>

{| class="wikitable"
|-
| <span style="font-size: x-large; font-family: serif;">∑</span>| ''y''<sub>''i''</sub> + ''s'' = 1|-
| ''i''| |}

the mixture properties must be properly calculated. On the other hand, if <span class="texhtml">γ<sup>''j''</sup></span> becomes zero then <span class="texhtml">''s''<sup>''j''</sup></span> can be relaxed and the model continues to bee solved without regard for that mixture.

The library can be used to perform just <span class="texhtml">''T''</span> and <span class="texhtml">''p''</span> equilibrium and fractions are computed by specification of relative volatilities. This kind of equilibrium is easier to compute and can be used as a first guess to solve the full equilibrium.

The following set of equations is a special representation of relative volatilities

:<math>{\bar \alpha}^j y_i^j = {\bar \alpha}_i^j y_i^{\mathrm{ref}}</math>

where <span class="texhtml">''j'' = 1,..''n''<sub>phases</sub> − 1</span>, and <span class="texhtml">''i'' = 1,..''n''<sub>components</sub></span>. To make it easier to understand the goal of this representation let's see what these equations represent for a two phase system (V,L) of the two components (A,B).

:<math>{\bar \alpha} y_A^V = \alpha_A^V y_A^L</math>

:<math>{\bar \alpha} y_B^V = \alpha_B^V y_B^L</math>

in the relative volatility model you fix the <span class="texhtml">α</span> values and compute the <math{\bar \alpha}</math>. Note that <math>\alpha_A^V / {\bar \alpha}</math> will be a K-value. Before seeing the model in action let's do some accounting. To simplify, we suppose a two-phase system, since ASCEND is not yet able to compute liquid-liquid models.

FIXME: add the equation-counting table here.

=== Chemical potential equilibrium ===

In the full equilibrium model, the Gibbs free energy for each phase is equated. To choose full equilibrium, you should set the variable '''<tt>equilibrated</tt>''' to <tt>TRUE</tt>.

:<math>{\bar g}_i^j = {\bar g}_i^{\mathrm{ref}}</math>

for each partial component and each phase except the reference one.

When using this model <math>\bar \alpha</math> is fixed and equal to one and the <span class="texhtml">α</span>'s are released and computed by equation 23. This equation becomes a computation of K-values. Now let's see the infamous accounting table for this model.

FIXME equation-counting for VL-equilibrium G-model.

Now let's look at some more examples.

=== Example 4 ===

'''Calculate the change of enthalpy for a 50% water, 50% ethanol being heated from 300 K to 400 K at constant atmospheric pressure.'''

This is a simple problem but it's useful for introducing the correct way to use the <tt>thermodynamics</tt> model.

<source lang="a4c">MODEL howto_thermo_ex8 REFINES cmumodel;

cd IS_A components_data(['water','ethanol'], 'water');
pd IS_A phases_data('VL', 'ideal_vapor_mixture', 'UNIFAC_liquid_mixture',

'none');
equilibrated IS_A boolean;
phases ALIASES pd.phases;

FOR j IN phases CREATE
smt[j] IS_A select_mixture_type(cd, pd.phase_type[j]);

END FOR;
FOR j IN phases CREATE
phase[j] ALIASES smt[j].phase;

END FOR;

state IS_A thermodynamics(cd, pd,phase, equilibrated);

METHODS
(* ... *)
METHOD values;
state.P := 1 {atm};

state.T := 300 {K};
state.y['ethanol'] := 0.5;

equilibrated := TRUE;
END values;
(* ... *)
END howto_thermo_ex8;</source>

Use of the thermodynamics model is slightly more complex. First, you should define the components data, then you choose the models for the phases with the <tt>phases_data</tt> model. This model's first parameter is a phase definition (it can be <tt>V</tt>, <tt>L</tt>< or <tt>VL</tt>), then the name for the vapour model (or <tt>none</tt> if there's not vapour phase), and then the liquid model name. The last parameter is for a second liquid phase model when <tt>LL</tt> equilibrium is implemented; for now, you should just use <tt>none</tt>.

The <tt>select_mixture_type</tt> model builds the chosen models so that they can be sent to the main thermodynamic model as a parameter. This may seem complicated at first, but as you probable will never need to change that piece of code, you don't need to worry about it too much. Just peek at the library code when you feel brave enough.

The value definitions are very simple; just notice the newly introduced <tt>equilibrated</tt> variable.

When solving multi-phase models you should always check <tt>state.slack_PhaseDisappearance</tt>. Only if it's zero the phase exists. Sometimes you can get strange results if you're looking at properties of a non-existent phase.

If you run the model, you'll get only a liquid phase and <span class="texhtml">''H''</span> = -282.351 kJ/mol. With <span class="texhtml">''T''</span> = 400 K, you'll get <span class="texhtml">''H''</span> = -233.022 kJ/mol, and so <span class="texhtml">Δ''H''</span> = 49.329 kJ/mol.

=== Example 5 ===

'''Build the VL equilibrium chart for water-ethanol at atmospheric pressure.'''

The model presented in the last example specifies <span class="texhtml">''p''</span> and <span class="texhtml">''T''</span>. To build an equilibrium chart, it's better to specify <span class="texhtml">''p''</span> and a mole fraction, and to free <span class="texhtml">''T''</span>. That way, we can be sure to have an equilibrium. The following method, added to the last example model, uses that trick. We'll also use the Pitzer vapour model, in the hope of improving accuracy.

<source lang="a4c">MODEL howto_thermo_ex9 REFINES cmumodel;
cd IS_A components_data(['water','ethanol'], 'water');

pd IS_A phases_data('VL', 'Pitzer_vapor_mixture', 'UNIFAC_liquid_mixture',
'none');

equilibrated IS_A boolean;
phases ALIASES pd.phases;
(*...*)

METHOD reset_Px;
equilibrated := TRUE;
RUN state.specify;

state.T.fixed := FALSE;
state.phase['liquid1'].y['water'].fixed := TRUE;

state.P := 1 {atm};
state.y['ethanol'] := 0.5;

state.phase['liquid1'].y['water'] := 0.6;
END reset_Px;

END howto_thermo_ex9;</source>

Now, instead of calling <tt>reset</tt> and <tt>values</tt> just run <tt>reset_Px</tt>. We'll run the model several times and build a table like the following:

{| class="wikitable"
|-
! <math>y_w^L</math>
! <math>y_w^V</math>
! <span class="texhtml">''T'' / [''K'']</span>
|-
| 0.99

| 0.8786
| 369.764
|-
| 0.95
| 0.652
| 362.471
|-
| 0.9
| 0.5517

| 358.80
|-
|  :
|  :
|  :
|}

When building the table, you must take some care for a phase not to disappear. You can do that by changing the variable <tt>state.phase['liquid1'].y['water']</tt>.

[[Category:Documentation]]
[[Category:Examples]]

Boundary detection

2010-05-13T14:01:24Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

<div class="pageexperimental">''This page documents an '''experimental''' feature. You can help out by '''testing it''' and <span class="plainlinks">[http://ascendwiki.cheme.cmu.edu/index.php?title=Boundary_detection&action=edit recording]</span> your experiences.''</div>

Boundary detection works under [[IDA]] to detect when, as moving forward in time, a point comes when a conditional expression changes value.

Possible boundaries include

* real-valued relations, such as <tt>t < t_1</tt> or <tt>T > T_sat</tt>
* boolean-valued relations, such as <tt>motor_running = (have_power AND motor_switch_on)</tt>

As integration time progresses, logic-valued relations can only change value when somehow triggered by changes in real-valued relations. Boolean-valued relations at that point then be re-evaluated using [[LRSlv]] to precedence-order the logical relations from the current model state.

Boolean-valued relations case use the truth-value of real-valued relations using the <tt>SATISFIED(relname,tolerance)</tt> function.

See also [[Conditional modelling]] and [[Integration of Conditional Models]].

[[Category:Experimental]]
[[Category:Documentation]]

ASCEND source code repository

2010-05-13T14:01:14Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

ASCEND source code and documentation files are maintained in a '''Subversion''' repository hosted by CMU.

== Checking out a copy of the code ==

To check out a local copy of the ASCEND source code, use your subversion client (see ''About Subversion'' below) to checkout from the repository URL <tt>[http://ascendsvn.cheme.cmu.edu/ascend/code/trunk]</tt>. To do this with the command-line client, you would typically use the following commands:

<source lang="a4c">cd ~/src
svn co svn://ascend.cheme.cmu.edu/ascend/code/trunk ascend</source>

Note that if you are behind a proxy, you may not be able to access our Subversion repository. Some proxies prevent access via the 'svn:' protocol. You may find some useful information in the [http://subversion.apache.org/faq.html Subversion FAQ].

You can also '''[http://ascendcode.cheme.cmu.edu/ browse the repository]''' online via ViewVC.

See [[BuildingAscend]] for information on how to build ASCEND from the source code you have checked out.

Please try to read our [[coding style]] guidelines.

<div style="width:110ex;padding-top:8px;padding-bottom:12px;border:solid 2pt gray;background-color:#ffff88;margin-top:5px;margin-bottom:5px;padding:8px">Our repository URL was changed ('svn:' instead of 'http:') on 2 Jun 2009. If you have a working copy that was checked out before this date, you will need to use 'svn switch --relocate' to update your working copy to the new server URL. The suggested command is:<br /><tt>svn switch --relocate http://ascendsvn.cheme.cmu.edu/ascend svn://ascend.cheme.cmu.edu/ascend</tt></div>

== Working on the documentation and website ==

The documentation is available as part of the source distribution above. We do this so that we can link in sample code directly when compiling the documentation.

The source material for the [http://ascend.cheme.cmu.edu public website] (as opposed to this wiki) hosted is a separate part of the Subversion repository however. You can check out the website files using:

<source lang="a4c">svn co svn://ascend.cheme.cmu.edu/ascend/web/trunk ascend-web</source>

We don't currently have an automated publishing script; you will need to manually update the webserver if you make changes there in the repository.

== Some Subversion automation ==

When making a commit to Subversion, you should be able to enter special strings like "fixes bug NNN", and those messages will be processed by the [http://ascendbugs.cheme.cmu.edu/ ASCEND Bug Tracker] and used to modify the status of a bug which is relevant to your changes. (Need confirmation that this is still operating correctly).

If you use the the [http://ascendbugs.cheme.cmu.edu/ ASCEND Bug Tracker], then anytime you write comments containing text like "changeset 345", the text will be converted into a hyperlink that will allow you to click through to review the relevant code changes on ViewVC.

== Branches ==

We have a number of active branches in our repository. Mostly these are related to our recent participation in [[Category:GSOC2009|GSOC 2009]].

== About Subversion ==

'''Subversion''' is the version management software we are using.

For '''Linux''', most distributions come with command-line subversion (command <tt>svn</tt>) already installed.
GUI clients are also available. See the links on [http://subversion.tigris.org/]. There is also now a useful Nautilus extension called [http://www.rabbitvcs.org/ RabbitVCS].

For '''Windows''', you will need to download and install a Subversion client. A recommended GUI client for Windows is [http://tortoisesvn.tigris.org/ TortoiseSVN]. The command-line client can also be run conveniently via [http://www.cygwin.com cygwin].

For '''MacOS X''', a recommended GUI client is [http://scplugin.tigris.org/ scplugin]. It allows you to access Subversion functionality for the context menu in the Finder. Alternatively, there is also a command-line version available for use from the Terminal.

[[Category:Development]]

DATA

2010-05-13T14:01:04Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

'''DATA''' instances are used to pass 'additional parameters' to [[External_relation|external relations]]. This can be used for example to define constants that are required for calculation of the external relation, but which do not vary over the duration of a simulation.

DATA instances are used for example in [[FPROPS]] to specify the fluid being used:

<source lang="a4c">MODEL ammoniadata;
component IS_A symbol_constant;
component :== 'ammonia';

END ammoniadata;

MODEL example;

(* variables that will be calculated (or specified, in some cases *)
p IS_A pressure;

T IS_A temperature;
rho IS_A mass_density;
h IS_A specific_enthalpy;

(* this is the 'DATA' instance that will be passed to the external relation *)
propsdata IS_A ammoniadata;

(* declare the external relation, together with the variables and DATA that it uses *)
props1: helmholtz_p(

T, rho : INPUT;
p : OUTPUT;

propsdata : DATA
);
END example;</source>

See also [[External_libraries#DATA_instance]].

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

Sensitivity study

2010-05-13T14:00:54Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

Non-proprietary Optimization

2010-05-13T14:00:45Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

{{task}}

We are trying to locate a suitable non-commercial optimizer to build into ASCEND. This would alleviate the current dependence on the proprietary [[CONOPT]] optimizer.

This task is currently being worked on by a [http://socghop.appspot.com/org/home/google/gsoc2009/ascend Google Summer of Code student].

== Requirements for New Optimizer ==

Mathematical/algorithm requirements:

* Must be able to handle 'box constraints', eg <math>a \le x \le b</math> for each variable.
* Must be able to handle equality constrains, eg <span class="texhtml">''g''(''x'',''y'',''z'') = 0</span> and <span class="texhtml">''x'' = ''f''(''y'',''z'',''a'',''b'')</span>
* Must be able to handle non-linear problems
* If matrix algebra is required, should use sparse methods rather than dense
* Should be able to make use of derivatives

Open questions:

* Should be able to handle general inequality constraints, eg <math>g(x,y,z) \le 0</math> ?
* Should ''not'' assume convex problem?
* Should ''not'' require second derivatives/Hessian matrix?
* Should be able to handle non-linear constraints?

Supporting information requirements:

* Should be known to solve a range of comparable problems to those which we expect to encounter
* Must be accompanied by a set of solvable problems for which exact solutions are known, for testing purposes.
* Should have a published algorithm
* Must have a user's manual
* Should have a freely-available user's manual

Pedantic legal stuff:

* Must be freely available to academics
* All requirement dependencies must be freely available to academics
* Should be freely available to everybody
* Should be redistributable in unmodified source form
* Should be redistributable in modified source form
* Should be redistributable in binary (compiled) form
* Documentation should be redistributable in original form
* Documentation should be redistributable in modified/repackaged form

== Background info ==

Related stuff:

* [http://en.wikipedia.org/wiki/Hessian_matrix Hessian matrix]
* [http://en.wikipedia.org/wiki/Karush-Kuhn-Tucker_conditions Karush-Kuhn-Tucker conditions]
* [http://en.wikipedia.org/wiki/Interior_point_method Interior point method]
* [http://en.wikipedia.org/wiki/Sequential_quadratic_programming Sequential quadratic programming]
* A [http://en.wikipedia.org/wiki/Category:Optimization_algorithms list of optimisation algorithms].
* A [http://orion.uwaterloo.ca/~hwolkowi/mirror.d/glossary/index.php glossary of Mathematical Programming (i.e. optimisation) terms].

We have done our own cursory [[survey of optimisation software]]

== TRON ==

Some work was done to investigate possible adding support for [[TRON]] in ASCEND. TRON can only solve the limited optimisation problem:

<math>
\begin{align}
\min f(\mathbf{x}) \\
\mathbf{x}_{lower} \le \mathbf{x} \le \mathbf{x}_{upper}
\end{align}
</math>

The following are observations:

* TRON requires that you write your own iteration loop ''outside'' TRON itself.
* TRON requires that you evaluate the function value and Hessian matrix (in a special compressed form that involves a vector of diagonal values then compressed column form for the off diagonal values, which being symmetric only need to cover half the matrix (so compressed column == compressed row?).
* TRON updates the variable vector and tells you when an optimum has been found.
* It's up to you to count iterations and terminate if it's taking too long etc.
* It seems fairly conceivable that solving more general systems with TRON might be possible by performing a separate NLA problem solution each iteration. But we're hesitant about trying that, because we're not completely comfortable with the maths involved in doing that at this stage, and not sure if it will mess up considerations of feasibility/optimality from TRON's PoV.

== IPOPT ==

IPOPT solves a more useful type of problem that includes equality constraints:

<math>
\begin{align}
\min f(\mathbf{x}) \\
\mathbf{c}_L \le \mathbf{c}(\mathbf{x}) \le \mathbf{c}_U \\
\mathbf{x}_L \le \mathbf{x} \le \mathbf{x}_U
\end{align}
</math>

It is emphasised that solving equality constraints is done just by setting elements of <math>\mathbf{c}_L</math> and <math>\mathbf{c}_U</math> equal to each other.

IPOPT supports a number of linear solvers including the HSL routine MA27, but also MUMPS, which is a free open source solver. So it is now possible to distribute a full working copy of IPOPT with ASCEND. It is also possible to have 'drop-in' support for HSL, because IPOPT can detect and dlopen HSL at runtime, if present.

Download/build instructions are here:
[http://www.coin-or.org/Ipopt/documentation/node18.html]

== MOOCHO / rSQP++ ==

The way that MOOCHO is packaged for download is as part of the big '''Trilinos''' bundle. This is a huge download that takes more than an hour to build on my system.

An RPM has been built for the Trilinos bundle, including MOOCHO. Get it from:
[http://software.opensuse.org/download/home:/jdpipe/]

The support for generic linear algebra routines is also now deprecated, and they are going for all-out integration with the other Trilinos packages. That means there's quite a lot to learn about. It's a bit daunting -- if anyone else fancies helping out, by all means, please do.

[[Category:Proposed]]

Canvas-based modeller for ASCEND

2010-05-13T14:00:36Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

{{task}}<div class="thumb tright"><div class="thumbinner" style="width:307px;">[[Image:Freeda-screenshot.jpg]] <div class="thumbcaption"><div class="magnify">[[File:Freeda-screenshot.jpg|<img src="/skins/common/images/magnify-clip.png" width="15" height="11" alt="" />]]</div>The canvas-based model of [http://www.freeda.org/ fREEDA], an electrical circuit simulator. This canvas is based on [http://trolltech.com/downloads/opensource Qt].</div></div></div><div class="thumb tright"><div class="thumbinner" style="width:307px;">[[Image:Gaphor-screenshot.png]] <div class="thumbcaption"><div class="magnify">[[File:Gaphor-screenshot.png|<img src="/skins/common/images/magnify-clip.png" width="15" height="11" alt="" />]]</div>Screenshot from [http://gaphor.sourceforge.net/ Gaphor] a [http://en.wikipedia.org/wiki/Unified_Modeling_Language UML] tool. This canvas is pure Python on top of Cairo.</div></div></div>
Many other modelling environments provide a graphical flowsheet modeller, or 'canvas' onto which unit operations are arranged to create a process flow diagram (PFD). '''We would like to be able to do this in ASCEND too.''' Currently this is being worked on by [[User:Arijit]] as a GSOC project. The goals are

* <strike style="color:green">create a new empty flowsheet</strike> <span style="color:green">(done)</span>
* <strike style="color:green">plop 'blocks' onto a canvas to represent various 'unit operations' such as tank, turbine, pump, column, resistor, capacity, actuator, motor, etc.</strike> <span style="color:green">(done)</span>
* <strike style="color:green">wire up the 'ports' on these blocks using 'connectors' that would correspond to 'streams' with multiple variables and parameters within them, such as a steam flow, or single variables such as a voltage signal.</strike> <span style="color:green">(done)</span>
* <strike style="color:green">view and edit parameters for the blocks in order to make adjustments to the system design.</strike>
* view and edit constants and sets for the model (eg name of the fluid in a stream).
* solve the model: <strike style="color:green">export to solver</strike>, give error message feedback, create linkage between blocks and solver vars. <span style="color:green">(partially done)</span>
* <strike style="color:green">see graphically the parts of the model which have not converged or which are out-of-bounds.</strike> <span style="color:green">(done)</span>
* <strike style="color:green">view the values of variables within the blocks once it has solved</strike> <span style="color:green">(done)</span>
* <strike style="color:green">save the flowsheet in such a way that when reloaded, it can again be solved afresh.</strike> <span style="color:green">(done)</span>
== Progress report ==
'''''Note:''' Canvas-based modeller is currently out of action due to recent API changes in Gaphas, the canvas toolkit that we're using. You can follow the <a href="https://ascendbugs.cheme.cmu.edu/view.php?id=424" class="external text" title="https://ascendbugs.cheme.cmu.edu/view.php?id=424" rel="nofollow">bug report</a> for details.''
<div class="thumb tright"><div class="thumbinner" style="width:307px;">[[Image:Gaphas-blocks.png]] <div class="thumbcaption"><div class="magnify">[[File:Gaphas-blocks.png|<img src="/skins/common/images/magnify-clip.png" width="15" height="11" alt="" />]]</div>Screenshot of the prototype Gaphas-based canvas for ASCEND</div></div></div>We have got a basically-functional 'canvas' widget now based on [[Gaphas]], with 'blocks', 'ports' and connector lines (see figure). A 'palette' is created based on markup of ASCEND models in the model library with NOTES as specified below. Blocks can be created by clicking in the palette then clicking in the canvas. And connector lines are created by draging from one 'port' to another. Blocks can be saved and restored, using Python Pickle functionality.

Canvas models can now be exported to the solver and ASCEND can attempt to solve them. However, there is currently no means for setting the parameters of Blocks, so there is no simple way of using a canvas model to solve specific problems. There is also not yet any way of viewing the resulting solution!

We 'mark up' MODELs as being blocks suitable for canvas-based modelling, using the [[NOTES]] framework. We can mark blocks, and also mark variables within them as being inputs or outputs, as follows:

<source lang="a4c">MODEL pump_simple;
ADD NOTES
'block' SELF {Simple model of a pump}

END NOTES;
inlet "in:" IS_A stream;
outlet "out:" IS_A stream;

inlet.mdot, outlet.mdot ARE_THE_SAME;
dp IS_A delta_pressure;

outlet.p = inlet.p + dp;
END pump_simple;</source>

Metadata currently implemented is

* name for the block (via NOTE of lang 'block', also is used to tell ASCEND that the object is indeed a block)
* what variables are the 'inputs' (via inline NOTES starting with 'in:')
* what variables are the 'outputs' (via inline NOTES starting with 'out:')
* what variables are parameters for a particular block (via inline NOTES starting with 'param:')
* icon used to display the block in the block palette (via NOTE with lang 'icon')

=== Two possible approaches to canvas-based models ===

There were two choices of ways that canvas-based 'blocks' could be declared using the ASCEND modelling language: parametric models or non-parametric models, which are shown below:

<source lang="a4c">(* parametric model *)
MODEL pipesegment(
inlet "in:" WILL_BE stream;

output "out:" WILL_BE stream;
dp WILL_BE delta_pressure;

);
inlet.h = outlet.h;
inlet.p + dp = outlet.p;

END pipesegment;</source>

and

<source lang="a4c">(* non-parametric model *)
MODEL pipesegment;

inlet "in:" IS_A stream;
output "out:" IS_A stream;

dp "param:" IS_A delta_pressure;
inlet.h = outlet.h;

inlet.p + dp = outlet.p;
END pipesegment;</source>

In the first case, the pipesegment model does not contain all the necessary variables, and it is not possible to create the pipesegment object without first creating the necessary parameter models 'inlet' and 'outlet'. On the other hand, this type of model is clearer in some ways because it effectively makes a distinction between 'private' (internal) variables and 'interface' variables (the ones that define its relationship with other models).

=== Problem with 'ARE_THE_SAME' in parametric models ===

In order to make models smaller, sometimes it's desirable to use [[ARE_THE_SAME]] to wire up variables that will always be the same, for example the mass flowrate into a unit and the mass flow rate out of the unit, in the case where there is no mass holdup. There are cases where it is mathematically preferable to use '=' instead of merging two variables, but it's nice to have the flexibility to choose between these.

The problem with using parametric models, though, is that it's not possible to merge parameter variables inside a parametric model, because this is not implemented or supported in the ASCEND compiler.

=== Problem with 'equality loops' ===

When wiring up loops of variables, such as constant flow rate through a loop, one cannot use '=' relations, because the system ends up overspecified. We would need a special solver to eliminate the unnecessary constraint, eg when three items are wired up in a constant-flow-rate loop:

<source lang="a4c">mdot1 = mdot2;
mdot2 = mdot3;
mdot3 = mdot1; (* this equation is a redundant *)</source>

On the other hand, using ARE_THE_SAME eliminates this problem, and rather than an overconstrained system, we just end up with one free variable:

<source lang="a4c">mdot1, mdot2 ARE_THE_SAME;
mdot2, mdot3 ARE_THE_SAME;

mdot3, mdot1 ARE_THE_SAME; (* ASCEND ignores this one, because the variables are already the same *)</source>

Although it is possible to design a solver such that the redundant equations are ignored, it was considered (by John) to perhaps be 'safer' modelling practise to require the user to specify a 'square' system without the solver having to ignore particular equations. So the ARE_THE_SAME system of wiring up models is currently preferred, but perhaps in future we will want to revisit this.

=== Parameters for blocks ===

In creating a canvas-based model, it is certainly not enough just to 'wire up' blocks are then expect the resulting model to do something useful. Most blocks will need to have some parameters set. For example, a pump may need to have its flow-rate or output pressure specified; a boiler will need to have its fuel supply rate and efficiency specified. Some blocks will require many parameters. It is also possible that blocks may need to be able to be used in multiple 'modes', for example a pump may have its efficiency and speed specified, or perhaps its efficiency and volumetric flow rate.

Currently, the parameters that a block provides can be marked up with NOTES as shown

<source lang="a4c">MODEL pump;
eta "param:isentropic efficiency" IS_A fraction;

f "param:rotational speed" IS_A inverse_time;
(* ... *)
END pump;</source>

In these cases, the canvas GUI can then specify (FIX and set) these variables in the resulting auto-generated MODEL. We still need to provide a GUI to allow the user to set and adjust these variables. It remains to determine what should happen in the case of multiple parameter 'modes' for a model.

=== Pickling to load/save canvasses ===

We are using the Python 'pickle' module to save and load canvas data. The models are loaded and saved divorced from and corresponding ASCEND instance data, in other words, they are a recipe for how to build up the ASCEND model, rather than a saved copy of the model itself. When the canvas is loaded, each block is 'reconnected' to the appropriate ASCEND objects, such as TypeDescription objects for the MODEL which each Block represents.

When we get further along, the pickles will also need to include the values of user-set parameters, and perhaps optionally the current solved value of the model, so that different canvases can be saved with different scenarios recorded therein.

=== What do do about connections? ===

When connecting two blocks together, up to now we have simply been providing ARE_THE_SAME statements to merge the two connector port sub-models. This approach is not fully general, and still leaves the possibility of equality loops in the model, for the case where, ''within the blocks''', "=" statements are used to express equality between, for example, input and output flowrates in a block.

To allow dynamic models to be represented on the canvas, we can't expect to use ARE_THE_SAME statements within blocks, because that would eliminate the possibility of modelling mass holdups. So, we need to think about using another kind of model generation that fixes this problem relating to the degrees of freedom in models generated from the canvas GUI. We're still discussing a solution.

=== Zoom and Pan ===

The canvas currently supports some mouse-friendly zoom and pan manipulations:

* Zoom using ctrl+wheel
* Pan using middle-button drag
* Zoom using ctrl+middle-button drag (up and down) (this option is provided for easier use on laptops with trackpads)
* Pan up and down using mouse wheel.

We still need to implement support for zoom-to-fit in the GUI.

== Next steps ==

It remains to implement:

* what do do where there is are multiple 'parameter modes' for the model.
* what to do about 'constants' in the model, eg when specifying a fluid, what fluid is to be used? when specifying a [[data reader]] block, what is the input file?
* customisable appearance of the block (perhaps via a NOTE of lang 'graphic', which might point to an SVG file, for example?)
* an alternative way of specifying inputs and outputs that doesn't use inline NOTES (eg a NOTE lang named 'in', perhaps? Would allow inputs to be declared elsewhere from the model itself.
* type-checking to ensure that only compatible ports are connected (this is not straightforward, could be done by exporting to the compiler and checking for error messages?)

== Loading, saving and solving canvas-based models ==

The above contains the minimal data required for the [[Library]] to be parsed and a 'palette' of available model 'blocks' presented to the user. The next question is: how should the resulting model be loaded, saved, and solved?

For the canvas-based model the essential data structures would contain

<div style="border:solid 1pt #DDDDDD; width:40em">

* list of modules used in the canvas
* list of blocks
** type of each block
** size and position of the block on the canvas
** name of the block
** block styling: colour, style?
** type of each block
** size and position of the block on the canvas
** name of the block
** block styling: colour, style?
* type of each block
* size and position of the block on the canvas
* name of the block
* block styling: colour, style?
* list of connections
** starting block and port (as blockname.portname)
** ending block and port
** line routing (a series of x,y points)
** line styling: colour, width, etc?
** starting block and port (as blockname.portname)
** ending block and port
** line routing (a series of x,y points)
** line styling: colour, width, etc?
* starting block and port (as blockname.portname)
* ending block and port
* line routing (a series of x,y points)
* line styling: colour, width, etc?
* list of other canvas objects
** text labels, headings etc
** possible 'output cells' that report current values of variables in the model
** possible 'method buttons' that run methods on the model.
** possible 'input cells' that allow variable values to be specified
** text labels, headings etc
** possible 'output cells' that report current values of variables in the model
** possible 'method buttons' that run methods on the model.
** possible 'input cells' that allow variable values to be specified
* text labels, headings etc
* possible 'output cells' that report current values of variables in the model
* possible 'method buttons' that run methods on the model.
* possible 'input cells' that allow variable values to be specified
* list of parameter values
** block to which the parameter blocks (maybe recursive).
** value of the parameter.
** units in which parameter has been specified.
** block to which the parameter blocks (maybe recursive).
** value of the parameter.
** units in which parameter has been specified.
* block to which the parameter blocks (maybe recursive).
* value of the parameter.
* units in which parameter has been specified.
</div>

With the above information it would be possible to save and reload a canvas-based model without loss of information, but note that the model would still have to be solved; it would not be saving the full state. It would have to be assumed that the model library upon which the canvas was based had not changed; certain debugging would be required to ensure that such a situation didn't result in a corrupted canvas-model. The above data might possibly be stored in a new file format '.a4g' specific to canvas-based modelling. (We could see the '.a4g' format as a sub-type of the '.a4c' format (in which case the above metadata might be embedded in NOTES, or similar?)

To solve a model with the above information, the approach would depend on whether the parametric or non-parametric modelling style is chosen.

For the parametric style, we would need to create definitions of the different streams ''before'' the blocks could be declared. This could lead to some ambiguity in the way that different streams are initialised, possible.

For the non-parametric style, we would only need to declare the blocks using [[IS_A]], then declare the connections using [[ARE_THE_SAME]]. We would want to have some sort of hierarchical system of [[METHODS]] to ensure that the necessary variables were FIXed and initialised for each block in the model (similar to the proposed 'default_self' recursion that is currently a bit broken).

There need to be some protocols about how the model would be intialised, in any case.

It should be possible to re-solve the model after the user changes a value of a parameter. This would mean that canvas-gui would have exported the model to the solver, and would then know how its blocks corresponded to variables in the model, and would call var_fixed or similar routines via the 'libascend' API.

It appears that the right approach would be for the canvas-based GUI to generate a string or file-based representation of the model it has in member, using the above hierarchy of objects (modules, blocks, connectors, but ''not'' parameter values), then to instruct ASCEND to load that model, then to [[FIX]] and set the values of the parameters, then attempt to 'solve' the model. This might be done in cooperation with the existing PyGTK GUI, or might be done directly with calls to the libascend engine. the canvas-based GUI would have no awareness of the variables it contained other than that provided by the connector end-point names and the parameter names. Using those names it would be able to get/set values in the simulation.

It would be possible to avoid the need for the canvas GUI to be able to [[FIX]] or [[FREE]] variables in the model. When a 'source' block was required, it could be set up as a new 'block' and the necessary un-FIXed variables left as parameters to the model. Changing the source block to another type would allow other parameters to be fixed. When greater flexibility was required, the user could switch to the non-canvas GUI.

== Design considerations ==

Do connections have properties and variables that need to be accessible, or is it always OK to access those variables/values via the connected blocks at either end?

What to do with the standard [[METHODS]] like [[Specify]], [[Default self]], [[Values]]?

How can we store the current state of the model? Should we try to do that?

How do we keep track of the fixed/free variables? Do we need to?

What about clashes between the [[Values]] methods in different submodels setting values on their 'connection' members. Is this the corner-case that makes the parametric approach more desirable? Or does that not actually solve the problem?

How can the canvas modeller determine when a model is 'complete'?

Is it OK to leave dangling lines?

Is it OK to leave unconnected 'ports' on the sub-models?

Is it better to use '=' relationships instead of ARE_THE_SAME? It seems that in some cases this leads to models that solve more reliably.

Line routing is tricky and something that is not often done well. Could use some cool [http://immi.inesc-id.pt/cali/applications.html calligraphic code] to make this work better

Could it be possible to highlight parts of the flowsheet corresponding to solved and un-solved portions of the model?

== Software ==

Programs that implement these types of GUIs include

* [http://gaphor.sourceforge.net/ Gaphor], written in pure python, uses [[Gaphas]] on top of [http://www.cairographics.org/ Cairo].
* [http://www.freeda.org/ fREEDA] ([http://www.freeda.org/screenshots.html screenshot]) (FOSS, Windows-based, uses a [http://en.wikipedia.org/wiki/Qt_(toolkit) Qt] canvas widget)
* [http://www.geda.seul.org/ gEDA]'s schematic editor, [http://www.geda.seul.org/tools/gschem/ gschem] is a GPLed GTK+ application that appears to use its own bespoke canvas implementation ([http://www.geda.seul.org/screenshots/ screenshots]). In a very quick and superficial test-drive, it appeared to be a little clumsy to use -- hard to identify when a connection has successfully been made, and fairly dated bitmap-style graphics.
* [http://www.lis.inpg.fr/realise_au_lis/kicad/ kicad] is another free electronic circuit schematic editor.
* [http://opencircuitdesign.com/xcircuit/index.html XCircuit] is a Tcl/Tk-based circuit editor.
* TRNSYS, Simulink, Visio, Dia, OOo Draw
* [http://kepler-project.org/ Kepler] (nice multi-domain canvas-based simulation, in Java)
* [http://www.cocosimulator.org/index.html COCO simulator] (windows, closed-source freeward)
* [http://www.conduit-project.org/wiki/Screenshots Conduit] (uses goocanvas)
* [http://www.gnome.org/projects/dia/ Dia] (seems to use GnomeCanvas?)
* [http://gstreamer.freedesktop.org/modules/gst-editor.html GStreamer Editor] (uses GnomeCanvas)
* [http://dwsim.inforside.com.br/ DWSIM] (sequential-modular simulator implemented in VB.net)
* Dunnart (testbed for libavoid)
* Inkscape (apparently includes support for libavoid, for automatic connector routing)
* [http://jmcad.sourceforge.net/ JMCAD] (java-based tool, seems to focus on nonlinear control)

Software libraries that could be used for this functionality (most are discuss [http://live.gnome.org/ProjectRidley/CanvasOverview here]):

* [[Gaphas]] (uses only Cairo, via pure Python)
* [http://live.gnome.org/ProjectRidley/CanvasOverview/Canvases/#goocanvas GooCanvas] (uses Cairo inside)
* [http://developer.gnome.org/doc/books/WGA/gnome-canvas.html GnomeCanvas] (not sure if it's deprecated yet or not, uses libart inside)
* [http://live.gnome.org/Criawips/CriaCanvas libccc/CriaCanvas] (uses Cairo inside)
* [http://www.cairographics.org/ Cairo] (directly)
* [http://www-eleves-isia.cma.fr/documentation/OpenInventorDoc/SoGtk/classSoGtk.html SoGTK] (use the OpenInventor 3D scenegraph for 2D work here?)
* Papyrus
* [http://adaptagrams.sourceforge.net/libavoid/ libavoid] (automatic connector-line routing including obstacle avoidance)

... it needs to be something that works within GTK and perhaps also PyGTK.
... we want to choose something that will be around for a while. The only canvas widgets from the above that is in Ubuntu and linked against are GooCanvas and GnomeCanvas, with GnomeCanvas being much more used than GooCanvas. libccc is available in Ubuntu but noone is linking against it yet (as of Hardy release)

[[Category:Proposed]]

Arrays and sets

2010-05-13T14:00:24Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

<div>''This article is incomplete or needs expanding. Please help out by adding your comments.''</div>
This page will be expanded to include use of SETs and arrays in ASCEND. For the moment here are some quick examples:
<source lang="a4c">REQUIRE "atoms.a4l";

MODEL mymodel;
(* declare a new set -- but note that its members could be declared in a sub-model if desired *)
myset IS_A set OF symbol_constant;

(* declare the members of the set -- note, this is done in the declarative section because the set is constant-valued *)
myset :== ['A','B','D'];

(* declare an array that contains elements indexed by the members of the myset *)

myarray[myset] IS_A distance;

(* write a relationship between the values of this array *)
myarray['A'] = myarray['B'] + 1;

METHODS
METHOD on_load;
(* fix all members in myarray *)
FIX myarray[myset];

(* free just one member *)
FREE myarray['A'];
END on_load;
END mymodel;</source>

See also [[Thin-walled tank/Arrays]].

== [[FOR]] loops ==

ASCEND provides looping syntax. The syntax used depends on whether you are in the declarative (main) part of your model (FOR..CREATE), or in the procedural part of the model (FOR..DO).

See the [[FOR]] for more information.

== Counting elements in sets using <tt>CARD</tt> ==

In ASCEND, the function '''<tt>CARD[set]</tt>''' can be used to count the number of elements in a set. A typical use is as follows:

<source lang="a4c">A IS_A set OF symbol_constant;

A :== ['A','B','C','D'];
n_A IS_A integer_constant;

n_A :== CARD[A];</source>

Now the value of n_A will be set to 4.

'''Note''': you can't use the <tt>CARD</tt> function in equations; it is only able to be used when assigning values to constants.

== Adding and subtracting sets ==

Sets can be useful for slicing up arrays in different ways, for example:

<source lang="a4c">REQUIRE "atoms.a4l";
MODEL mymodel;
A, B, C IS_A set OF integer_constant;

A :== [1..10];
B :== [1,2,9,10];

C :== A - B; (* set difference, will contain 3,4,..8. *)

a[A] IS_A temperature;

n_C IS_A integer_constant;
n_C :== CARD[C];

T_avg_C IS_A temperature;
T_avg_C * n_C = SUM[a[i] | i IN C];

METHODS
METHOD on_load;
(* fix elements 1, 2, 9 and 10 *)
FIX a[B];

(* initialise those same elements to 290 K *)
FOR i IN B DO
a[i] := 290 {K};

END FOR;
(* initialise the remaining elements to 320 K *)
a[C] := 320 {K};

END on_load;
END mymodel;</source>

Note the use of the [[SUM]] statement for looping through elements of a set and adding up the resulting expressions.

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

Worked examples

2010-05-13T14:00:14Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

This is a list of worked example models that were written in the spirit of experimentation while working on the functionality of ASCEND.

See also [[Category:Tutorials]] and [[Category:Examples]].

== Four bar linkage ==

{{src|models/johnpye/fourbar.a4c}}

This example shows a (static) system with simple geometric constraints. It is solved for a range of angles for one member, and the position of the other members is determined. Then a nice plot is built up by repeated running the ASCEND model and accumulating the results using [[ExtPy]].

<div class="thumb tnone"><div class="thumbinner" style="width:402px;">[[Image:Fourbar.png]] <div class="thumbcaption"><div class="magnify">[[File:Fourbar.png|<img src="/skins/common/images/magnify-clip.png" width="15" height="11" alt="" />]]</div>both</div></div></div>

== Thermal equilibrium ==

{{src|models/johnpye/thermalequilibrium2.a4c}}

This is a simple model of thermal equilibrium between two masses of steam with a simple constant heat transfer coefficient between them. The model uses external [[freesteam]] IAPWS-IF97 steam tables and the [[IDA]] integrator.

<div class="thumb tnone"><div class="thumbinner" style="width:402px;">[[Image:Thermalequilibrium.png]] <div class="thumbcaption"><div class="magnify">[[File:Thermalequilibrium.png|<img src="/skins/common/images/magnify-clip.png" width="15" height="11" alt="" />]]</div>Graph of the temperatures of the two masses over time. The transition through the saturation region is visible.</div></div></div>

== Simple advection equation ==

{{src|models/johnpye/advection.a4c}}

This model is a study of the simple advection equation, following [http://dx.doi.org/10.1177/003754977803100205 a discussion] published by Carver and Hinds in ''Simulation'' (1978). Just as with the explicit integration method discussed in that paper, we also see instability when using the [[IDA]] implicit BDF integrator here. The output in each case was generated by copying the contents of the Integrator tab and pasting into OpenOffice and plotting there.

[[Image:2p-upwind.png]][[Image:3p-upwind.png]]
[[Image:4p-biased.png]][[Image:Central-diff.png]]

== More examples ==

For some more detailed examples, see the page [[Category:Examples]], which includes:

* [[Vapor-liquid equilibrium]]
* [[Calculation of sun position]]
* [[Damped response]]
* [[Conditional modelling]] (examples of models with IF/ELSE-style behaviour in their equations)
* [[Optimisation of frame geometry]]
* [http://www.che.uah.edu/courseware/toolbox/ascend/ Chemical thermodynamics, mass/energy balance] and more, from [[User:Kchittur|Krishnan Chittur]].

[[Category:Documentation]]
[[Category:Examples]]

ANTLR exercise

2010-05-13T14:00:04Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

ANTLR is a candidate for replacing yacc/lex as the parser in ascend. This is needed for many reasons, of which a key one is generating C-code versions of models that are thread safe so we don't have to clean up the current model interpreter. There are several other very good reasons for ANTLR:

* We want to do source-to-source translation of ascend models to other languages that give us optimization access (GAMS, AMPL, OSxL, Matlab).
* Similarly, we want to be able to dump a canned C or Fortran version of a model for standalone (non-ascend) use.

The exercise is to demonstrate just the parsing with antlr of the current ascend language, with particular attention to the portions of the language defined in compiler/scanner.l (the lex/flex input file).

The current parser/scanner are in compiler/ascParse.y and compiler/scanner.l.

Notable differences between ascend and other languages are the NOTES feature of ascend and the fact that comments in ascend nest, unlike C/Java.

Building ascend and installing Antlrworks is probably a good place to start.

[[Category:GSOC2010]]

Supporting RPMs

2010-05-13T13:59:54Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

RPM packages (.rpm files) can be used on Red Hat and Fedora systems, SUSE and some other linux distributions. Any open-source RPMs that we generate in our efforts to getting ASCEND running, we will upload here.

== SUNDIALS ==
<div class="notice metadata" id="outdated" style="border:solid 2pt orange; width:70ex; background-color:#FFEEDD;padding:4px;margin-bottom:6px">''This article is '''outdated'''. You can help out by <span class="plainlinks">[http://ascendwiki.cheme.cmu.edu/index.php?title=Supporting_RPMs&action=edit updating it]</span>. ''</div>

As of quite recently, SUNDIALS is available in the Fedora 7 and Fedora 8 repositories, so you shouldn't need to use our home-baked version unless you are on Fedora Core 6 or earlier.

* Fedora Core 6: <a href="/images/b/bc/Sundials-2.3.0-0.i386.fc6.rpm" class="internal" title="Sundials-2.3.0-0.i386.fc6.rpm">sundials-2.3.0-0.i386.fc6.rpm</a>
* Source RPM for Fedora: [http://ascend.cheme.cmu.edu/ftp/jpye]
* Experimental RPMs for other platforms: [http://download.opensuse.org/repositories/home:/jdpipe/]
* We are currently in the process of submitting SUNDIALS for inclusion in Fedora.

== CONOPT ==

We have a CONOPT RPM that can be supplied to registered users of [[CONOPT]] only.

== IPOPT ==

* Experimental RPMs for Fedora, SUSE and others: [http://download.opensuse.org/repositories/home:/jdpipe/]
* When SUNDIALS has been accepted for inclusion into Fedora, we will start working on submitting IPOPT for inclusion.

== CUnit ==

* Experimental RPMs for Fedora, SUSE and others: [http://download.opensuse.org/repositories/home:/jdpipe/]

[[Category:Outdated]]
[[Category:Documentation]]

Prerequisites for Linux

2010-05-13T13:59:44Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

<div class="notice metadata" id="stub">''This article is a '''stub'''. You can help out by <span class="plainlinks">[http://ascendwiki.cheme.cmu.edu/index.php?title=Prerequisites_for_Linux&action=edit expanding it]</span>. ''</div>

== To Build ASCEND ==

You can usually just use the default versions of these that come with current versions of Linux. But just check them, anyway:

* gcc and g++ (3.x or 4.x)
* gfortran or g77 (we are recommending gfortran, because a FORTRAN-90 compiler is required if you want to build [[CONOPT]])
* flex
* bison
* python 2.4 or newer, including 'dev' package or similar
* [http://sourceforge.net/project/showfiles.php?group_id=30337&package_id=22359 scons] (1.x or 0.98.x)
* [http://sourceforge.net/project/showfiles.php?group_id=1645&package_id=1608 swig] (>=1.3.24). Some probs reported with 1.3.39.
* [http://www.llnl.gov/CASC/sundials/ sundials] (>=2.2.0) or note that [[Supporting_RPMs|we have an RPM]]
* Tcl/Tk 8.3 or newer
* Tktable 2.8 or newer
* graphviz (optional)
* blas (optional, for use by LSODE solver; ASCEND also can build its own)
<br />
OpenSUSE is very out of date with SCons. You will not be able to use their version (as of May 2007).

== To Run ASCEND ==

The PyGTK GUI:

* gtk+
* pygtk
* matplotlib
* numpy
* libsundials (see [[Building ASCEND]] for note regarding Ubuntu Edgy)
* IPython (optional)
* graphviz (optional)

To run the Tcl/Tk GUI:

* Tcl/Tk 8.3.x or 8.4.x (whichever was used for the build)
* TkTable 2.8 or 2.9
* xgraph

See also [[Prerequisites for Windows]].

[[Category:Stubs]]
[[Category:Documentation]]

Library

2010-05-13T13:59:34Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

<div class="notice metadata" id="stub">''This article is a '''stub'''. You can help out by <span class="plainlinks">[http://ascendwiki.cheme.cmu.edu/index.php?title=Library&action=edit expanding it]</span>. ''</div>

In ASCEND, the '''Library''' is the place where loaded modules are stored in memory. It is effectively a collection of 'type_description' objects, which can be instantiated into '''model''' trees then sent to the solver.

See also [[MODEL|'''MODEL''']].

[[Category:Stubs]]
[[Category:Development]]

REFINES

2010-05-13T13:59:24Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

The '''REFINES''' keyword is used to declare models as specialisations of more general 'base' models.

<source lang="a4c">MODEL vehicle;
n_wheels IS_A integer_constant;
END vehicle;

MODEL bicycle REFINES vehicle;
n_wheels :== 2;
END bicycle;

MODEL car REFINES vehicle;
n_wheels :== 4;
END car;</source>

See also [[Object-oriented modelling]].

[[Category:Syntax]]

Thin-walled tank/Adding methods to a model

2010-05-13T13:59:15Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

<div style="float:right;width:33ex;padding-left:3px;margin-left:10px;margin-bottom:10px;border:solid 2pt grey;background-color: #eee">
'''''''''Thin-walled''' tank tutorial
<br /><small>[[Thin-walled_tank|←Return to start]]</small>

* [[Thin-walled_tank/Introduction|Introduction]]
* <strong class="selflink">Adding methods to a model</strong>
* [[Thin-walled_tank/Arrays|Arrays]]
* [[Thin-walled_tank/Building_complex_models|Building complex models]]
* [[Thin-walled_tank/Parameterized_models|Parameterised models]]

See also [[Category:Tutorials|Other tutorials]]
</div>
In this part, we continue the example we introduced in Part 1. Our goal is to provide an introductory tutorial into using the ASCEND modeling environment. We shall show how to add METHODS to models to make them more useful for sharing with others and/or with oneself at a later time.

== Introduction: making a model sharable==

We shall say a model is sharable if one can use and understand it without being its developer. Being able to solve a model at least one time without first understanding it can aid significantly in learning about the model, especially in a modeling environment such as ASCEND that allows one to explore a solved model instance in detail.

In Part 1, our ASCEND model was a nonprocedural listing of the variables and equations that must be true at the model solution. There were no statements as to how to solve the model. We know that solving large nonlinear models can be very difficult numerically and can require the modeler to provide a lot of special knowledge to coerce the model to a solution. We want to add this knowledge to the code defining the model without forcing a modeler to use that knowledge when using the same model in a different manner - such as to solve for a different set of fixed variables or when embedding the model as a part of a larger model.

Our approach in ASCEND is to allow modelers to add any number of methods to a model. Methods are executable procedures that can alter the values of the variables and flags within a model instance and that can trigger the execution of other methods. One writes them within within a [[METHODS]] section for the model.

== Adding methods to the '''thin-walled''' tank model ==

The following is our '''thin walled''' tank example with an added [[METHODS]] section.

<source lang="a4c">(* this is file twt0210.a4c *)
REQUIRE "atoms.a4l";

MODEL thin_walled_tank;

(* fixed variables *)
D,
H,
wall_thickness IS_A distance;

metal_density IS_A mass_density;

(* computed variables *)
end_area,
side_area IS_A area;

wall_vol IS_A volume;
metal_mass IS_A mass;

(* equations *)

end_area=3.1416*D^2/4;
side_area=3.1416*D*H;

wall_vol=(side_area+2*end_area)*wall_thickness;
metal_mass=metal_density*wall_vol;

METHODS

METHOD specify;
FIX D;
FIX H;

FIX wall_thickness;
FIX metal_density;
END specify;

METHOD values;
D := 20.0 {cm};
H := D/10.0;

wall_thickness := 0.15 {cm};
metal_density := 7.85 {g/cm^3};

END values;

METHOD setup;
RUN specify;

RUN values;
END setup;

END thin_walled_tank;</source>

We include three methods: specify - to set the fixed flags for the fixed variables, values - to provide values for these four fixed variables and setup - to trigger the running of the other two methods. A user of this model within the TclTK interface would load it, compile it, and export it to the solver. With a tool within the solver, he would trigger the method "setup" to run. Finally he would solve the well-posed model. Note that he could do all these steps without understanding anything about the model. When done, he would have a solved model instance that he could then examine in detail using many of the available tools.

A method is a procedure. Thus statements that set values for the variables are of the general form

<source lang="a4c">LHS variable := RHS expression;</source>

This statement states that ASCEND is to replace the value of the LHS variable with the current value of the RHS expression. The replacement equals (:=) is not the equation equals (=) that we used in the nonprocedural part of our model.

==Discussion==

Note that the METHODS section provides procedures a model user can invoke only when he wishes. Running "setup" blindly sets up his model for solving. As the original modeler will have tested this model before making it available, he would know that running "setup" creates a model instance that will solve. He has thus passed this information along to the subsequent user, making the model more sharable than before.

Also note that the second user of this model does not need to use any of these methods. It is still a model he could play with interactively in many other ways. It has just provided him with one way to get a first solution to examine.

==Standardized set of methods==

We advise modelers using ASCEND to develop a number of different methods for a model. That these methods exist and are useful is supported by our experiences with using ASCEND. Note that no method has to be there. We give several of these methods standard names, and both the TclTk and PyGTK interfaces discover and trigger some of these methods automatically when compiling and solving a model. A significant difference between the two interfaces is the number of methods each expects and triggers automatically, with the PyGTK using methods as a means to make one's first experience with a model appear to be very simple. We describe here the methods these interfaces anticipate being in a model.

See also [[METHODS]].

Continue with [[Thin-walled_tank/Building_complex_models|the next section, Building complex models]]

[[Category:Examples]]
[[Category:Tutorials]]

Obtaining CONOPT for ASCEND

2010-05-13T13:59:04Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

[[CONOPT]] is an advanced optimisation ([[NLP]]) solver available that is supported by ASCEND. CONOPT is commercial software, and as such can not be distributed with ASCEND's GPL-licensed code.

A paid license for CONOPT costs 640 USD for an academic single-user license, or 3200 USD for a non-academic license. These are the same prices as for the GAMS version of the CONOPT solver. To be elegible to use the academic license, CONOPT must used for teaching and/or non-commercial research, i.e. not for consulting.

The ASCEND project receives a fixed percentage of the CONOPT license fee, so this is a good way to support our project as well.

'''Note''': CONOPT has been tested with ASCEND on Linux (Fedora 9, Ubuntu 9.04) as well as Windows (XP). It is likely to be OK on other platforms, but may need some testing.

== Trial copy ==

A two-month trial of CONOPT is available for users of ASCEND.

If you would like to obtain a trial copy of CONOPT please send us your details and whether you will be using it for academic or non-academic purposes. We will send you a suitable version of CONOPT (Linux RPM, Windows .EXE, or Linux .so file), and will also pass on your details to Arne Drud, who may wish to contact you to follow up on your experience with CONOPT.

Alternatively, you can obtain a trial copy yourself from the <tt>libconsub3.so</tt> file that is distributed with the [http://download.gams-software.com/ GAMS download]. Drop the file in <tt>/usr/lib</tt> and ASCEND should detect it. If you can't put it there, set the <tt>CONOPT_PATH</tt> environment variable to the correct directory before launching ASCEND.

When CONOPT is correctly installed, it will appear in the 'Tools→Solver Engine' menu in the PyGTK GUI for ASCEND.

Arne Drud ([http://www.conopt.com]) has very generously permitted this two-month trial usage of CONOPT. We would ask that you respect his request that you only use the trial version for 2 months, after which time please remove it from your machine, or pay for a license.

See also [[CONOPT]].

[[Category:Solvers]]

Prerequisites for Windows

2010-05-13T13:58:54Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

== For ASCEND 0.9.7 with the Python GUI ==

To be installed in this order:

* [http://www.python.org/ftp/python/2.6/python-2.6.msi Python 2.6] (be sure to install the 32-bit version)
* [http://ftp.gnome.org/pub/GNOME/binaries/win32/glade3/3.6/glade3-3.6.7-with-GTK+.exe Glade with GTK+ 3.6.7]
* [http://ftp.gnome.org/pub/GNOME/binaries/win32/pygobject/2.14/pygobject-2.14.2-2.win32-py2.6.exe PyGObject 2.14.2 py2.6]
* [http://ftp.gnome.org/pub/GNOME/binaries/win32/pycairo/1.4/pycairo-1.4.12-2.win32-py2.6.exe PyCairo 1.4.12-2 py2.6]
* [http://ftp.gnome.org/pub/GNOME/binaries/win32/pygtk/2.16/pygtk-2.16.0.win32-py2.6.exe PyGTK 2.12.1-3 py2.6]

Optional components:

* [http://ipython.scipy.org/dist/0.10/ipython-0.10.win32-setup.exe IPython 0.10] (for console support)
* [http://sourceforge.net/projects/numpy/files/NumPy/1.3.0/numpy-1.3.0-win32-superpack-python2.6.exe/download NumPy 1.3.0] (to support Matplotlib)
* [http://sourceforge.net/projects/matplotlib/files/matplotlib/matplotlib-0.99.1/matplotlib-0.99.1.win-amd64-py2.6.exe Matplotlib 0.99.1] (for plotting and incidence matrices)

Backup copies of many of the above files are available from [http://www.eng.uah.edu/~kchittur/files4windows this site].

== For ASCEND 0.9.7 with the Tcl/Tk GUI ==

The ActiveState site has recently removed the Tcl/Tk installer that was required by ASCEND during installation. A copy of the original file is available from here:

* [http://www.eng.uah.edu/~kchittur/files4windows/ActiveTcl8.4.15.0.280619-win32-ix86-threaded.exe]

We also believe that the following release will work, but have not yet tested it:

* [http://downloads.activestate.com/ActiveTcl/releases/8.4.19.3/ActiveTcl8.4.19.3.291941-win32-ix86-threaded.exe]

== For ASCEND 0.9.6 with the PyGTK GUI ==
<div class="notice metadata" id="outdated" style="border:solid 2pt #FDB; width:70ex; background-color:#FFF8F4;padding:4px;margin-bottom:6px">''This section is '''outdated'''. You can help out by <span class="plainlinks">[http://ascendwiki.cheme.cmu.edu/index.php?title=Prerequisites_for_Windows&action=edit updating it]</span>. ''</div>
<div style="border:solid 2pt blue;padding:5px">ASCEND now supports Python 2.5. (See link to sourceforge.net download page below). If installing ASCEND with Python 2.5, be sure to get the <tt>-py2.5</tt> versions of the dependencies listed below. We have tested ASCEND with more up-to-date versions (than those listed here) of the GTK and PyGTK and related packages and that seems to work OK as well.</div>

First install Python [http://www.python.org/download/releases/2.4.4/ version '''2.4''']. We are not yet supporting Python 2.5 on Windows (although it is tested on Linux and should work).

Next install GTK+. Download the [http://downloads.sourceforge.net/gladewin32/gtk-win32-devel-2.6.10-rc1.exe gtk-win32-devel-2.6.10-rc1.exe] file from the [http://sourceforge.net/project/showfiles.php?group_id=98754&package_id=111411 gladewin32] project.

Next, install the following additional reqired python-related packages on your machine (easily located with Google):

* [http://ftp.gnome.org/pub/gnome/binaries/win32/pycairo/1.0/pycairo-1.0.2-1.win32-py2.4.exe pycairo-1.0.2-1.win32-py2.4.exe]
* [http://ftp.acc.umu.se/pub/gnome/binaries/win32/pygtk/2.6/pygtk-2.6.3-1.win32-py2.4.exe pygtk-2.6.3-1.win32-py2.4.exe]

You will require the following (for versions up to ASCEND 0.9.5.109, or they are optional for 0.9.5.110) for graphics support:

* [http://downloads.sourceforge.net/matplotlib/matplotlib-0.90.0.win32-py2.4.exe matplotlib-0.90.0.win32-py2.4.exe]
* [http://prdownloads.sourceforge.net/numpy/numpy-1.0.2.win32-py2.4.exe numpy-1.0.2.win32-py2.4.exe]

The remaining packages are optional. If you want to enable [[Python console support]] for scripting/debugging:

* [http://ipython.scipy.org/dist/ipython-0.8.0.win32.exe ipython-0.8.0.win32.exe]
* (another python extension module), which in turn requires
** [http://downloads.sourceforge.net/ctypes/ctypes-1.0.1.win32-py2.4.exe ctypes-1.0.1.win32-py2.4.exe] (note: this dep will drop off with Python 2.5 -- built-in)
** [http://ipython.scipy.org/dist/pyreadline-1.4.2.win32.exe pyreadline-1.4.2.win32.exe]
** [http://downloads.sourceforge.net/ctypes/ctypes-1.0.1.win32-py2.4.exe ctypes-1.0.1.win32-py2.4.exe] (note: this dep will drop off with Python 2.5 -- built-in)
** [http://ipython.scipy.org/dist/pyreadline-1.4.2.win32.exe pyreadline-1.4.2.win32.exe]
* [http://downloads.sourceforge.net/ctypes/ctypes-1.0.1.win32-py2.4.exe ctypes-1.0.1.win32-py2.4.exe] (note: this dep will drop off with Python 2.5 -- built-in)
* [http://ipython.scipy.org/dist/pyreadline-1.4.2.win32.exe pyreadline-1.4.2.win32.exe]

== For ASCEND 0.9.6 with the Tcl/Tk GUI ==

* Tcl/Tk 8.3 or [http://downloads.activestate.com/ActiveTcl/Windows/8.4.15/ActiveTcl8.4.15.0.280619-win32-ix86-threaded.exe 8.4 (ActiveState distribution)]
* TkTable 2.8 or 2.9 (link required here?)
* xgraph (optional)

== CONOPT ==

Optionally, if you want to use the [[CONOPT]] or [[CMSlv]] solvers, you will need CONOPT. We have a .exe installer that we can provide to registered users of CONOPT.

See also [[Prerequisites for Linux]].

[[Category:Outdated]]
[[Category:Documentation]]

Environment variables for ASCEND

2010-05-13T13:58:44Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

<div class="notice metadata" id="stub">''This article is a '''stub'''. You can help out by <span class="plainlinks">[http://ascendwiki.cheme.cmu.edu/index.php?title=Environment_variables_for_ASCEND&action=edit expanding it]</span>. ''</div>

The following environment variables affect how ASCEND runs.

== ASCENDLIBRARY ==

This variable defines the search path that is used when attempting to load files named on the command line or named in [[REQUIRE]] statements.

This variable a PATH-style variable, which means that on Windows it is semicolon-delimited, whereas on Linux it is colon-delimited. If you are using MSYS/MinGW then be aware that there is no magical transformation; you still need to us semicolons.

When ASCEND loads, the following methods are used in order of decreasing priority:

* the ASCENDLIBRARY environment variable, if present
* the value of <tt>librarypath</tt> from <tt>~/.ascend.ini</tt>, if defined.
* (Windows only) the value of the registry variable <tt>HKLM\SOFTWARE\ASCEND\ASCENDLIBRARY</tt>, if defined
* the default value defined at compile-time.
'''The following is possibly subject to revision:'''

The '''exception''' to this is that ''if'' the ASCENDLIBRARY variable is defined, but it ''does not'' contain the standard [[ASCEND Model Library]] folder (probably <tt>/usr/share/ascend/models</tt> or <tt>c:\Program Files\ASCEND\models</tt>), then it will be added to the '''end''' of the ASCENDLIBRARY path. This is to ensure that the model library will always be available for use with [[REQUIRE]] statements, and to make setting of non-standard paths a little more convenient.

See also [[REQUIRE]], [[IMPORT]].

== ASCENDSOLVERS ==

This variable is used in the <tt>package_load</tt> function that ASCEND uses in [[IMPORT]] statements, when loading external libraries, including solvers.

ASCEND defines a value for ASCENDSOLVERS when ASCEND is first launched. The value used is, in order of decreasing priority:

* The ASCENDSOLVERS environment variable if available (appending standard folder to end if it is missing),
* (Windows only) the registry key <tt>HKLM\SOFTWARE\ASCEND\ASCENDSOLVERS</tt>, if present, or
* a default value defined at compile time.

If ASCENDSOLVERS is not defined, ASCEND next looks for external libraries in the other locations indicated by the ASCENDLIBRARY environment variable, which means that you can store your external libraries as well as your model files in the same directory structure if you wish to.

'''The following is possibly subject to revision:'''

If the ASCENDSOLVERS environment variable is defined, and if it ''does not'' contain the standard <tt>solvers</tt> folder (probably <tt>/usr/share/ascend/solvers</tt> or <tt>c:\Program Files\ASCEND\solvers</tt>) then this folder will be added to the '''end''' of the ASCENDSOLVERS path. This is to ensure that the basic minimal set of ASCEND solvers is always available, to avoid confusion.

See also [[IMPORT]].

== ASCENDTK ==

This environment variable is used to define the location of the Tcl/Tk support files used by the ASCEND Tcl/Tk GUI. It defaults to <tt>$ASCENDDIST/TK</tt>. It has no effect on the PyGTK GUI.

== ASCENDBITMAPS ==

Defines the location of bitmap files used in the Tcl/Tk GUI. Defaults to <tt>$ASCENDDIST/bitmaps</tt>. It has no affect on the PyGTK GUI.

== ASCENDDIST ==

This environment variable is used by the ASCEND Tcl/Tk GUI to define the location of its common files. It can also be used to create 'off root' installations, by allowing ASCEND to locate its files using relative paths. Depending on compile-time settings (specifically the value of <tt>@ASC_ABSOLUTE_PATHS@</tt>), ASCENDDIST defaults to either <tt>$PROGDIR/@ASC_DATADIR_REL_BIN@</tt> or <tt>@ASC_DATADIR@</tt> (where the '<tt>@...@</tt>' variables are defined at compile time, and $PROGDIR is the directory containing the <tt>ascend4</tt> binary).

== ASC_GDB ==

If present and non-zero, causes the ASCEND PyGTK GUI to run via the <tt>gdb</tt> debugger (part of GNU GCC). This is made available because, since ASCEND PyGTK is essentially a Python program, it can be a little difficult/inconvenient to run it through a debugger.

== LD_LIBRARY_PATH ==

When launching ASCEND PyGTK, this environment variable is examined to ensure that it contains the location of <tt>libascend</tt> if necessary. If libascend is installed anywhere except /usr/lib, then its location is added to the end of LD_LIBRARY_PATH before continuing.

When using the [[IPOPT]] solver, it may also be necessary to use this env var to point to external solvers such as /usr/local/lib/libhsl.so.

[[Category:Stubs]]
[[Category:Documentation]]

External libraries

2010-05-13T13:58:36Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

ASCEND supports external libraries (you might call them 'plugins') of a number of different kinds. Specifically,

* external solvers (for solving [[NLA]] and possibly other types of problems such as MILP or MINLP)
* external integrators (for solving ODE/DAE problems)
* external methods (that can be called from inside [[METHODS]] using the [[EXTERNAL]] command)
* external relations (in other words, equations that are calculated using code outside ASCEND)
* external import handlers (more on this later)
Currently all solvers and integrators for ASCEND are implemented as external libraries, as well as a number of external methods including a wrapper for [[QRSlv]] and a Brent solver for 'homing in' on a solution to a single variable in otherwise hard-to-solve cases. There are also external libraries for calculation of steam properties (see [http://freesteam.sf.net]), properties of other fluids (see [[FPROPS]]) and for modelling of heat transfer in long-pipe flow boiling (ask [[User:Jpye|John Pye]]).

Some other external libraries are under development including one for interpolating time-series data for use in simulations with forcing data.

For large array-based simulations, external libraries may permit faster solution by eliminating unnecessary iteration by ASCEND and instead performing the iteration inside lower-level code.

== External methods ==
External methods can be used to implement procedural-style changes to your model via the [[EXTERNAL]] statement. This technique is used internally by ASCEND to implement the <tt>ClearAll</tt> method (see <a href="https://ascendcode.cheme.cmu.edu/viewvc.cgi/code/trunk/models/basemodel.a4l?view=markup" class="external text" title="https://ascendcode.cheme.cmu.edu/viewvc.cgi/code/trunk/models/basemodel.a4l?view=markup" rel="nofollow">basemodel.a4l</a>. Here is the syntax to call an load and call an external method in a simple model:

<source lang="a4c">IMPORT "mylibrary"; (* load libmylibrary.so or mylibrary.dll *)

MODEL mymodel;
...
METHODS
METHOD dosomething;
...

(* run a method from mylibrary... *)
EXTERNAL myexternalmethod(SELF);
RUN values; (* combine the EXTERNAL call with other statements as you wish *)

END dosomething;
METHOD values;
...
END values;

END mymodel;</source>

The [[IMPORT]] statement is used to specify how to load your external library; it is required that your external library contains a registration function that will tell ASCEND what external methods your library is providing.

== External relations (aka 'black box' relations) ==

External relations are implemented as '''blocks''' of equations that are evaluated in external code. This means that you pass a set of 'input' variables, and the external code evaluates the resulting values of the 'output' variables. In addition, there is a provision for a 'data' object to be passed to the code. This data object should be constant-valued, so it can contain values that the external code won't be changing.

To make use of an external relation (for example <tt>myextrel</tt> ) as declared in your library <tt>mylibrary</tt>, you use syntax like this:

<source lang="a4c">IMPORT "mylibrary"; (* ASCEND will try to load libmylibrary.so or mylibrary.dll depending your platform *)
...

x IS_A real;
A IS_A real; (* etc *)
eta IS_A real_constant;

data IS_A mymodel_data;

(* use a 'black box relation' from mylibrary... *)
my_external_relation: myextrel(
x, y, z : INPUT;

A, B : OUTPUT;
eta : DATA
);

...</source>

=== How external relations are used by ASCEND ===

External relations are solved to completion in the external code. When implementing your external relation, you should select your <tt>OUTPUT</tt> variables such that they can be calculated with certainty in terms of the <tt>INPUT</tt> and <tt>DATA</tt> variables. You can design your code to include its own internal iteration or solver procedure if necessary.

When a black box is added your model, it creates a 'relation' object for each of your <tt>OUTPUT</tt> variables, and makes this relation incident with its output variable as well as with ''all'' of the <tt>INPUT</tt> variables for the black box:

<div class="thumb tnone"><div class="thumbinner" style="width:402px;">[[Image:Blackbox-incidence.png]] <div class="thumbcaption"><div class="magnify">[[File:Blackbox-incidence.png|<img src="/skins/common/images/magnify-clip.png" width="15" height="11" alt="" />]]</div>Incidence matrix for a model containing a single 'black box' external relation containing 3 outputs and 9 inputs.</div></div></div>

When ASCEND reaches a block that contains external relations, it may find that all the INPUT variables are already known, in which case a single call the the external relation will be sufficient to determine the values of the OUTPUT variables. On the other hand, it may be that the values for some of the OUTPUT variables are already known (having been solved earlier in the solver process) and some of the INPUT variables are yet to be determined. In this case, ASCEND will use its standard Newton solver algorithm to home in on a solution for those variables. The external relation API provides the means for you to give a Jacobian matrix for the output variables relative to the input variables, which can then be used to improve the accuracy of the Newton solver. If you don't provide these derivatives, however, ASCEND will compute finite difference approximations by perturbing the values of the INPUT variables to estimate the Jacobian. Obviously this can result in many excess calls your your external relation evaluation function, so you will need to work out whether or not it is worth providing the derivative evaluation functions as well.

=== DATA instance ===

The '''<tt>DATA</tt>''' instance (see above example) is a mechanism whereby an arbitrary set of configuration data can be passed to the external relation when it is first set up.

<tt>DATA</tt> parameters are intended to convey fixed, constant values to the external relation. The best way to use these is to set up a <tt>MODEL</tt> containing various <tt>constant</tt> values:

<source lang="a4c">MODEL myext_data;

myvalue IS_A constant;
myvalue :== 3.45 {m};
END myext_data;</source>

These values can then be obtained in the external library code using (here C++) the following. The 'data' variable is passed in to the BBoxInitFn.

<source lang="a4c">symchar *myvalue_sym = AddSymbol("myvalue");
struct Instance *myvalue_inst = ChildByChar(data,myvalue_sym);

if(!myvalue_inst)throw runtime_error("Instance 'myvalue' is required in DATA");
double myvalue = RealAtomValue(myvalue_inst);</source>
'''Note''' that this is intended to be a '''read-only''' mechanism; there is no guarantee, if you attempt to 'hold on' to pointers into this DATA instance, that those instances will still be there later on.

See also [[Writing_ASCEND_external_relations_in_C|a more detailed example]] about external relations.

== External solvers ==

All ASCEND solvers are implemented as external libraries. This includes [[QRSlv]] as the default NLA solver, [[CONOPT]] as the standard optimisation solver, plus [[CMSlv]] as the conditional solver. See [[Solvers]] for more information.

Default solvers are loaded when ASCEND starts. To use other solvers, you must add an [[IMPORT]] statement at the start of your model file to trigger loading of the necessary shared library. Note the [[ASCENDSOLVERS]] environment variable can be used to located where these shared libraries are located, if necessary.

Somewhat related: we have implemented an experimental [[Goal seeking solver]] using the EXTERNAL method mechanism. This is suitable for implementing a 'shooting method' with an ASCEND model, for cases where a complicated model (for example one with some difficult feedback) doesn't converge when using the standard [[QRSlv]] solver.

See also [[External Solvers]].

== External integrators ==

Support for external ''integrators'' has also been implemented. This means that any new integrator your create can be loaded dynamically with the [[IMPORT]] statement. For example we provide [[DOPRI5]]:

<source lang="a4c">IMPORT "dopri5";</source>

For non-standard integrators, this additional IMPORT statement is required in order to for ASCEND to load the integrate. Standard integrators [[IDA]] and [[LSODE]] are always loaded, by default.
The integrator will then be available in the list when you open the 'Integrate' dialog.

See also [[External Integrators]].

== External import handlers ==

In a pleasing ''coup de récursion'', one can implement 'handlers' for importing other types of external libraries using the external library mechanism itself. For example, we have the [[ExtPy]] shared library, which, if [[IMPORT|IMPORTed]], allows one to then subsequently IMPORT external libraries defined by Python scripts. This mechanism is still somewhat hackish but has nevertheless proven useful in automating some modelling tasks, particularly when using the [[PyGTK GUI]].

See also [[Import Handlers]].

== External CALLs ==

This seems to be a fossil in the code. There is some provision for 'CALL' statements that do something with external code. Not sure still what that does. This might be the start of a system for performing calls to functions '''with arguments''' from ASCEND METHODs, which is currently not implemented in general.

== Writing an external library ==

We will assume you are implementing a 'native' external library, in other words one that loads from a shared library (.so or DLL file depending on your platform).

You will create a source code files <tt>extfn.c</tt> that will be complied into a shared library <tt>libextfn.so</tt> or a DLL <tt>extfn.dll</tt> depending on your platform.

Your source code needs file to contain a registration function named with the stem of the library name (<tt>extfn</tt>) with the added text <tt>_register</tt> added at the end. This will enable ASCEND to automatically discover the registration function for your external library.

Your <tt>*_register</tt> function will in turn contain one or more calls to the ASCEND <tt>CreateUserFunction</tt> function. These calls will register your external methods and functions, allowing them to be called from your <tt>.a4c</tt> file. Here is an example of a registration function:

<source lang="a4c">extern int
DLEXPORT mylibrary_register(struct Slv_Interp *dummy1, struct Instance *root
,struct gl_list_t *arglist, unsigned long dummy4

){
const char *addone_help = "This function will return one-plus-its-input-argument";
int result;

result = CreateUserFunction("add_one"
,(ExtEvalFunc *)addone_prepare
,(ExtEvalFunc **)addone_calc
,(ExtEvalFunc **)NULL
,(ExtEvalFunc **)NULL
,1, 1, addone_help
);

return result;
}</source>

Each call to <tt>CreateUserFunction</tt> can offer a 'preparation' function (which can be used to pre-calculate
fixed data tables and so on), an 'evalation' function (which will return your function value, plus
first and second derivative functions.

In order to compile your source code, you should use a SCons build file based on the example one given in <tt>models/johnpye/extfn</tt>. Note the useful <tt>ascend-config</tt> script that can help in determing your linker and compiler flags.

Your sourcecode must contain (one or more functions like) the <tt>mylibrary_register</tt> that you referenced in your IMPORT statement. This function must contain one or more calls to <tt>CreateUserFunction</tt> which will tell ASCEND about the functions you are offering in your shared library.

There are examples of such code in {{srcdir|models/johnpye/extfn}} in our [[ModelLibrary]].

An important concept is the [[ImportHandler]]. This is a mechanism whereby you can define new types of external functionality to your model, to be accessed by the <tt>IMPORT</tt> statement. This means that the <tt>IMPORT</tt> statement is overloaded and can be set up to import anything you like, so long as ASCEND has been told how to deal with it.

See also [[Writing ASCEND external relations in C]].

== Freesteam ==

The open source steam properties library '''freesteam''' ([http://freesteam.sf.net]) includes bindings to ASCEND via the external 'black box' system. There is a windows installer. Once installed, you need to edit you <tt>.ascend.ini</tt> file so that the directory <tt>c:\Program Files\freesteam\ascend</tt> is included in your <tt>librarypath</tt>. Freesteam works equally well under Linux, although there are no binary packages at this stage.

<div class="thumb tnone"><div class="thumbinner" style="width:502px;">[[Image:Thermalequilibrium.png]] <div class="thumbcaption"><div class="magnify">[[File:Thermalequilibrium.png|<img src="/skins/common/images/magnify-clip.png" width="15" height="11" alt="" />]]</div>A transient simulation of the equilibrium of two masses of water, showing phase change. The steam properties are calculated using [http://freesteam.sf.net/ freesteam]. The integration was performed using [[IDA]].</div></div></div>

[[Category:Documentation]]
[[Category:Extending_ASCEND]]
[[Category:Development]]

Talk:Data reader

2010-05-13T13:58:24Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

==Data Reader Talk Page==

Please capture here thoughts and ideas that might not be appropriate in the main page. Experimental features, corrections, toDO's, wishes, etc. The idea is to keep the page itself as documentation and let the talk page be the discussion/developement forum. [[User:JoseZapata|Jose Zapata]] 23:30, 26 July 2009 (UTC)

: TODO (high priority, very easy): Other file formats: we should add support for the Australian BoM's new RMY (prev TMY) file format. It's the same as ACDB format, but with three extra digits added to the end. <a href="/User:Jpye" title="User:Jpye">Jpye</a> 07:41, 27 July 2009 (UTC)
<dl><dd> Agree, would you like this done within GSOC? <a href="/User:JoseZapata" title="User:JoseZapata">Jose Zapata</a> 05:55, 12 August 2009 (UTC)
</dd></dl>

: Agree, would you like this done within GSOC? <a href="/User:JoseZapata" title="User:JoseZapata">Jose Zapata</a> 05:55, 12 August 2009 (UTC)

: TODO (high priority, moderate difficulty): Add support for CSV files. Bear in mind that Excel outputs files with quoting of (some/all?) values and some escape characters (eg \", not sure); a fully general implementation could be difficult. <a href="/User:Jpye" title="User:Jpye">Jpye</a> 07:53, 27 July 2009 (UTC)

<dl><dd> I dont think is worth the effort to code for a "MS proof" csv file AFAICT most software produce good quality CSV files (including Excel). If the data file is not properly formated, (as in values sepparated by commas and nothing else) the data reader should reject it. <a href="/User:JoseZapata" title="User:JoseZapata">Jose Zapata</a> 05:55, 12 August 2009 (UTC)
</dd></dl>

: I dont think is worth the effort to code for a "MS proof" csv file AFAICT most software produce good quality CSV files (including Excel). If the data file is not properly formated, (as in values sepparated by commas and nothing else) the data reader should reject it. <a href="/User:JoseZapata" title="User:JoseZapata">Jose Zapata</a> 05:55, 12 August 2009 (UTC)

: TODO (medium priority, moderately difficult): Support for lookup tables with two independent variables. For example, we could use it to code up Jeff's results on the efficiency of a dish field for different sun angles. Examples of independent variables would be altitude and azimuth angles. I believe that TRNSYS implements this kind of thing. This would require a generalised spline implementation. <a href="/User:Jpye" title="User:Jpye">Jpye</a> 07:41, 27 July 2009 (UTC)
<dl><dd> I thought a single independent variable was part of the scope definition for the data reader. I suppose it makes sense, specially for situations like dish efficiency fields where tabulation of data is faster than coding the efficiency algorithm like other extfunctions<a href="/User:JoseZapata" title="User:JoseZapata">Jose Zapata</a> 05:55, 12 August 2009 (UTC)

</dd></dl>

: I thought a single independent variable was part of the scope definition for the data reader. I suppose it makes sense, specially for situations like dish efficiency fields where tabulation of data is faster than coding the efficiency algorithm like other extfunctions<a href="/User:JoseZapata" title="User:JoseZapata">Jose Zapata</a> 05:55, 12 August 2009 (UTC)

: TODO (low priority, fiendishly difficult): Support for integer/boolean input data. There will be cases when input data could contain on-off stuff that we would like to feed into a simulation. Currently very difficult to implement, because the '''external''' relation interface only provides for rels, not logrels. <a href="/User:Jpye" title="User:Jpye">Jpye</a> 07:41, 27 July 2009 (UTC)
<dl><dd> I dont see how boolean data should be imported different from real data. The trick is in the interpolation. If a signal changes from 0 to 1 , what is the value in between? <a href="/User:JoseZapata" title="User:JoseZapata">Jose Zapata</a> 05:55, 12 August 2009 (UTC)
</dd></dl>

: I dont see how boolean data should be imported different from real data. The trick is in the interpolation. If a signal changes from 0 to 1 , what is the value in between? <a href="/User:JoseZapata" title="User:JoseZapata">Jose Zapata</a> 05:55, 12 August 2009 (UTC)

: TODO (medium priority, very easy): Add a link to a complete working example, preferable including a sample (CSV?) data file. <a href="/User:Jpye" title="User:Jpye">Jpye</a> 07:53, 27 July 2009 (UTC)

: TODO check monotonic increase of independent variable <a href="/User:JoseZapata" title="User:JoseZapata">Jose Zapata</a> 04:08, 24 August 2009 (UTC)

Real-time ASCEND

2010-05-13T13:58:14Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

{{task}}

We propose developing a system that allows realtime data to be incorporated into ASCEND simulations, both for computing the performance of realtime systems, as well as for performing realtime parameter estimation. This is a huge area, and work is just beginning.

<br />
Contributed by: [[Dipak Chirmade]]

== Integration of live data streams into ASCEND simulation ==

=== Detailed procedure ===

Please scroll down through the page to understand the overall work-flow diagram of current work.

Sub-pages:

* [[Real-time_ASCEND/Data_acquisition_hardware|Data acquisition (DA) hardware]]
* [[Real-time_ASCEND/Data_reader|Real-time Data reader]]
* [[Real-time_ASCEND/Solver|Real-time solver]]

=== Quick example ===

Following video demonstrate calculation of average of two live real-time temperature feeds. Please visit detailed procedure to learn more about real-time data reader and prototype of real-time solver.

<object width="400" height="329"><param name="movie" value="http://www.youtube.com/v/cxF2u_-KVE4"></param><param name="wmode" value="transparent"></param><embed src="http://www.youtube.com/v/cxF2u_-KVE4" type="application/x-shockwave-flash" wmode="transparent" width="400" height="329"></embed></object>

Source: [http://ascendcode.cheme.cmu.edu/viewvc.cgi/code/branches/dipak/models/dipak/Examples <font color="orange">dipak</font>:models/dipak/Examples]

=== Sequence diagram or work-flow of real-time ascend ===

''(With only major actions)''
<div class="thumb tnone"><div class="thumbinner" style="width:802px;">[[Image:DA_Sequence.jpg]] <div class="thumbcaption"><div class="magnify">[[File:DA_Sequence.jpg|<img src="/skins/common/images/magnify-clip.png" width="15" height="11" alt="" />]]</div>Sequence of operations at DA-Hardware side.</div></div></div>
<div class="thumb tnone"><div class="thumbinner" style="width:802px;">[[Image:DR_Sequence.jpg]] <div class="thumbcaption"><div class="magnify">[[File:DR_Sequence.jpg|<img src="/skins/common/images/magnify-clip.png" width="15" height="11" alt="" />]]</div>Sequence of operations at real-time data-reader side.</div></div></div>
<div class="thumb tnone"><div class="thumbinner" style="width:802px;">[[Image:RS_Sequence.jpg]] <div class="thumbcaption"><div class="magnify">[[File:RS_Sequence.jpg|<img src="/skins/common/images/magnify-clip.png" width="15" height="11" alt="" />]]</div>Sequence of operations at real-time solver side using Runge-Kutta method.</div></div></div>

[[Category:Proposed]]
[[Category:Miscellany]]

Survey of optimisation software

2010-05-13T13:58:04Z

UploadBot: Restored page from Google Cache, uploaded by John Pye

The following is a survey of optimisation software that was performed as a part of our effort to identify options for a [[Non-proprietary Optimisation]] solver for ASCEND. Feel free to add any that we've missed.

== List of Lists ==

* List of NLP solvers: [http://www.ici.ro/camo/hnp.htm]
* List of unconstrained optimisation solvers: [http://www.ici.ro/camo/huo.htm]
* There ''was'' a nice list at [http://www.scicomp.uni-erlangen.de/SW/opt.html] but the link seems to be broken at the moment.
* 'Decision tree' for optimization software [http://plato.asu.edu/sub/nlores.html]
* Description of different types of optimisation problems: [http://coool.mines.edu/report/node3.html]

== Free Open Source Software options ==

* <a href="https://projects.coin-or.org/Ipopt" class="external text" title="https://projects.coin-or.org/Ipopt" rel="nofollow">IPOPT</a> (LGPL) 'Interior-Point Filter Line-Search Algorithm'. Possibly some problems with scaling of variables (according to RPS). can use a number of free and non-free matrix solvers; the free matrix solver in version 3.3.1 is MUMPS. See also [[IPOPT]] in this wiki.
* [http://trilinos.sandia.gov/packages/moocho/ MOOCHO] (GPL?) reduced sequential quadratic programming (SQP); allows the user to supply their own linear solver.
* [http://www.gnu.org/software/gsl/manual/html_node/Multidimensional-Minimization.html GSL 'multimin'] (GPL) several multidimensional dense-matrix unconstrained optimisation methods including conjugate gradient methods, quasi-newton methods, steepest descent and Nelder-Mead simplex method.
* [http://acts.nersc.gov/opt++/index.html OPT++] (free, includes ''optional'' wrapping of non-free NPSOL). Good but dense matrices only (RPS). Superceded by MOOCHO?
* [http://software.sandia.gov/appspack/version5.0/index.html APPSPACK] (GPL?) 'asynchronous parallel generating set search', derivative-free.
* [http://www.eng.buffalo.edu/Research/MODEL/mdo.test.orig/CONMIN/ CONMIN] ('free' but where from?) 'two-step limited memory quasi Newton like Conjugate Gradient method with Beale restarts'.
* [http://www.cs.sandia.gov/SGOPT/ SGOPT] (LGPL) Evolutionary and pattern-search algorithms
* [http://www.math.ufl.edu/~hager/ OPTPACK] (PD) 'a dual algorithm for constrained optimization'
* [http://www.netlib.org/minpack/ MINPACK] (BSD-like) unconstrained
* [http://www.coin-or.org/Bonmin/ BonMin] (CPL) Part of the COIN-OR suite; a solver for convect MINLP problems.
* <a href="https://projects.coin-or.org/Couenne" class="external text" title="https://projects.coin-or.org/Couenne" rel="nofollow">Couenne</a> (CPL) Part of the COIN-OR suite; a solver for non-convex MINLP problems.
* [http://www.ime.usp.br/~egbirgin/tango/ ALGENCAN] (GPL) Augmented Lagrangian plus an embedded smooth function box-constraint solver called 'GENCAN'
* [http://www.ime.usp.br/~egbirgin/tango/ SPG] (GPL) for smooth function with convex constraint
* [http://www.gerad.ca/~couturgi/NOMAD/ NOMAD] (GPL) Generalized Pattern Search (GPS) algorithms to solve nonlinear optimization problems
* [http://www-fp.mcs.anl.gov/otc/Tools/LBFGS-B/ LBFGS-B] (PD?) limited-memory quasi-Newton code
* [http://ab-initio.mit.edu/wiki/index.php/NLopt NLopt] (LGPL) wrapper for a few other FOSS codes, but also reportedly has some new implementations of certain algorithms
* [http://www.uni-graz.at/imawww/kuntsevich/solvopt/ SolvOpt] (PD) 'method of exact penalisation', based on N.Z. Shor r-algorithm
* [http://openopt.org/ralg ralg] (BSD) - an implementation of N.Z. Shor r-algorithm; nonlinear/nonsmooth constrained/unconstrained problems

Wrappers

* [http://www.coin-or.org/NLPAPI/index.html NLPAPI] (GPL?) a generalised wrapper for NLP solvers, including support for LANCELOT.
* <a href="https://projects.coin-or.org/GAMSlinks/" class="external text" title="https://projects.coin-or.org/GAMSlinks/" rel="nofollow">GAMSlinks</a> (GPL?) a wrapper for <a href="https://projects.coin-or.org/" class="external text" title="https://projects.coin-or.org/" rel="nofollow">COIN-OR</a> solvers that allows them to be called from GAMS. This is interesting as it shows how we could implement set up ASCEND so that it can use GAMS solvers, which adapting FOSS solvers that run under GAMS much easier to adapt for use with ASCEND.
* [http://www.netlib.org/ampl/solvers/lancelot/ AMPL/LANCELOT] a wrapper for running LANCELOT from AMPL. Again, this provides a way for seeing how solvers that have been adapted for use in AMPL might be also be connected to from ASCEND.
* [http://cuter.rl.ac.uk/cuter-www/interfaces.html CUTEr] (GPL-like license) is a wrapper for a wide range of optimisation solvers, and also a testing framework.
* <a href="https://projects.coin-or.org/Osi" class="external text" title="https://projects.coin-or.org/Osi" rel="nofollow">OSI</a> (CPL?) wrapper for quite a wide range of LP solvers, from COIN-OR.
* <a href="https://projects.coin-or.org/OS" class="external text" title="https://projects.coin-or.org/OS" rel="nofollow">OS</a> (CPL?) Optimisation Services, a number of interface languages and APIs for communicating between problem 'servers' and solver 'clients', with support for a range of COIN-OR solvers and converters for GAMS/AMPL input files.
* [http://wiki.services.openoffice.org/wiki/Optimization_Solver OpenOffice.org's Solver]
* [http://openopt.org OpenOpt] (BSD) a general purpose optimization framework written in Python and NumPy, capable of automatic differentiation.

Unknown:

* [http://coool.mines.edu/ COOOL]

Another free list: [http://software.sandia.gov/Acro/html/Main/AcroPackages.html]

There are some more listed in the <a href="ftp://rtfm.mit.edu/pub/usenet/sci.answers/nonlinear-programming-faq" class="external text" title="ftp://rtfm.mit.edu/pub/usenet/sci.answers/nonlinear-programming-faq" rel="nofollow">nonlinear-programming-faq</a>.

== Free for non-commercial use ==

Trust region

* [http://www.numerical.rl.ac.uk/lancelot/blurb.html LANCELOT] (no redistribution or resale) Trust region method, adapt for bound constraints

Active set

* [http://www-unix.mcs.anl.gov/~more/tron/ TRON] (permission to copy and modify, but only to be used for 'internal research' ([http://plato.asu.edu/ftp/other_software/tron_f90.tar.gz download]) active set method that uses a combination of gradient projections and a preconditioned conjugate gradient method to minimize an objective function. TRON only provides for 'box' constraints and has no support for equality constraints, although it may be possible to add support for that by wrapping TRON around an NLA solver?

Sequential quadratic programming

* [http://plato.la.asu.edu/donlp2.html DONLP2] (dense; free for non-commercial purposes)

== Some proprietary alternatives ==

Generalised reduced gradient method:

* [http://www.conopt.com/ CONOPT] (plus others in certain cases)
* [http://www.sbsi-sol-optimize.com/asp/sol_product_minos.htm MINOS] (uses GRG for linear constraints, else 'sparse SLC algorithm (a projected Lagrangian method, related to Robinson's method)' for nonlinear constraints. Used when gradient evaluation is cheap.
* MS Excel [http://support.microsoft.com/kb/q214115/ Solver].
* GRG2
* LSGRG2
* [http://www.pinterconsulting.com/ LGO] 'Lipschitz Global Optimizer'

Sequential quadratic programming:

* [http://www.sbsi-sol-optimize.com/asp/sol_products_snopt_desc.htm SNOPT] (sparse) Used when gradient evaluation is expensive. 'SNOPT employs a sparse SQP algorithm with limited-memory quasi-Newton approximations to the Hessian of Lagrangian. An augmented Lagrangian merit function promotes convergence from an arbitrary point.'
* [http://www.uni-bayreuth.de/departments/math/~kschittkowski/nlpqlp22.htm NLPQLP]
* [http://www.sbsi-sol-optimize.com/asp/sol_product_npsol.htm NPSOL]
* [http://www.sbsi-sol-optimize.com/asp/sol_lssol105description.htm LSSOL] (dense, 'two-phase (primal) quadratic programming')
* [http://www.princeton.edu/~rvdb/ LOQO] (free 30-day trial) 'LOQO is based on an infeasible, primal-dual, interior-point method applied to a sequence of quadratic approximations to the given problem'
* [http://www.mcs.anl.gov/~leyffer/solvers.html FilterSQP]

Active set method:

* [http://www.sbsi-sol-optimize.com/asp/sol_product_qpopt.htm QPOPT] (dense)

Other methods:

* [http://www.ziena.com/knitro.htm KNITRO] (three methods: interior point direct, interior point conjugate gradient, 'active set')
* [http://www.gams.com/dd/docs/solvers/pathnlp.pdf PATHNLP]. 'PATHNLP solves an NLP by internally constructing the Karush-Kuhn-Tucker (KKT) system of first-order optimality conditions associated with the NLP and solving this system using the PATH solver for complementarity problems'. Supposedly good for convex problems.
* [http://www.mosek.com/products.html MOSEK] (limited version available for download, or free student license) Interior point method plus simplex method.
* [http://www2.am.uni-erlangen.de/~kocvara/pennon/ PENNON] 'penalty method', 'PBM method of Ben-Tal and Zibulevsky'

Global optimisation

* [http://www.andrew.cmu.edu/user/ns1b/baron/baron.html BARON]
* [http://www.ganso.com.au/index.php GANSO]

Methods not yet checked:

* IMSL and NAG software libraries
''More to come''

Mixed integer/nonlinear programs:

* [http://www.gams.com/solvers/solvers.htm#DICOPT DICOPT]: MINLP

See also [[Survey of sparse matrix software]]

[[Category:Development]]