READ ME RAMSES Extras

"RAMSES Extras" is an add-on to the ordinary RAMSES software package (RAMSES is an acronym for Research Aids for Modeling and Simulation of Environmental Systems). "RAMSES Extras" features latest extensions of RAMSES, like new modules not yet cast in stone and - quite essential - supports the use of Alpha as an editor.

To extract "RAMSES Extras" unstuff first the obtained file to get the folder "RAMSES x.y Extras" (e.g. use StuffIt Expander™). In unstuffed form, this folder contains all items of the release (Note, the installation process hasn't installed anything in your System folder, nor anywhere else). Actual installation needs to be completed manually. Note, this makes only sense after having installed the ordinary "RAMSES" release and typically the powerful editor Alpha. Get Alpha at http://www.kelehers.org/alpha/ or better from http://alphatcl.sourceforge.net/wikit/. Then follow these steps:

1) Move the entire content of the unstuffed folder "RAMSES x.y Extras" into your RAMSES folder. Then run the utility "Arrange_RMS" (under OS 9.x or earlier) or "Arrange_RMS_X "(under OS X; see disk image "Arrange OS X.dmg"), which you find in the folder "ExtraTools". If this utility asks you to select a folder, choose your RAMSES folder. As a result you will have a RAMSES folder with extended functionality. E.g. you have now a tool named "HierRFM", which analyzes import dependencies using ".RFM"-files or a tool named "BatchFiler" to operate on sets of files, e.g. files with a particular extension such as "*.MOD"-Files (see e.g. folders "ExtraTools" and "Docu"). In the folder "ExtraTools" you find many more tools, desk accessories and applications such as "SymDiff" to compare numerically two files of any format or "MapPackage", a small GIS utility to view maps given in form of ArcInfo files.

This step is already sufficient to enhance fully the functionality of RAMSES.

There are many more items contained in "RAMSES x.y Extras", which you may need to explore by investigating them individually. Many contain their own READ ME files, some are merely shareware redistribution, since we liked that shareware, others are our own creation. Of particular interest may be the following items contained in the release:

2) There are utilities available wich facilitate the installation of a RAMSES release including the merging of RAMSES Extras and ScienceLib files. Unpack file 'install_RAMSES.sit' as released here into a working folder you wish to use for installation purposes. Download the RAMSES files as available from the internet to this folder and then merely double-click file '__install_RAMSES.command'. Follow instructions and you should get RAMSES folder with the latest software and your Work folder from the previous release.

3) "Alpha Editor Support" (possibly now in folder "ExtraTools" within your RAMSES folder) contains the M2 mode which you need to use Alpha as an editor (http://alphatcl.sourceforge.net/wiki) together with RAMSES (or MacMETH) and RMSP1 (or RASS-OSX). However, normally there is actually no need to install this mode, should you use an Alpha 7.5 or later, since a M2 mode is preinstalled in current Alpha distributions. Otherwise, should you wish to install the M2 mode, for whichever reason, it is best you install the M2 mode by simply double-clicking the file "READ to AUTOINSTALL M2" (assumed you already have the Alpha editor installed and ready to run). Once "READ to AUTOINSTALL M2" is open, click on "HERE" under "Step 1" to trigger Alpha's convenient installation procedure. Just follow the suggested defaults. As a result Alpha should smoothly interact with the big RAMSES shell without any further customizations required, given you work on a PowerPC or later Macintosh (otherwise consult the installation instructions in "Modula-2 Help", topic «Installation», found in Alpha's Help menu (M2 mode >= V 3.7.2) or in file "READ to AUTOINSTALL M2").

You can use Alpha also together with the Mini RAMSES Shell. But to accomplish this, you have to enter the power user mode of the Mini RAMSES Shell (Cmd^Shift^Capslock^P, see also Help of the Mini RAMSES Shell). Then use the command "Preferences..." in the hierarchical menu "Power User" of the menu "Shell". To use Alpha instead of MEdit you have to select with button "Use..." the tool "AlphaEdit" from within folder "M2Tools" instead of "Edit2".

It is also possible to use Alpha together with the MacMETH shell. Make sure you use the right "User.Profile" depending on which shell you work with, i.e. the MacMETH or the RAMSES shell (see 2c).

Once you have installed the M2-mode, you can safely discard the folder "Alpha Editor Support". All help or other information is now installed within Alpha.

a) Note the folder "AuxLibExtra .DEF" must reside within folder "AuxLib" within folder "Docu" within the RAMSES folder in order to be accessible by the M2 mode of Alpha. Once installed in the right location, Command^double-clicks (or Command^Control^double-clicks) on a procedure's identifier while editing a module from within Alpha should now also open the extra quick reference file (or the added extra definition module which exports the procedure). Normally, utility "Arrange_RMS" (or "Arrange_RMS_X") places the folder where it belongs.

b) Depending which version of Alpha you are using, the "User.Profile" may need to be edited. There are User.Profile files provided within the folder "Alpha Editor Support". The "User.Profile" in folder "M2 Mode & RAMSES" is for RAMSES users, the one in "M2 Mode & MacMETH" for MacMETH users. The critical section of the User.Profile is the "Alias" section, which must exactly match your current installation. If you are using Alpha8, this section must look similar to this:

"Alias"

'Alpha' is '::Alpha:Alpha8'

More on this can be found in READ to AUTOINSTALL M2". Note, once a User.Profile has been edited, you should relaunch the RAMSES or MacMETH shell or reread the profile (menu "Shell > Read profile" or "File > ReadProfile").

4) "Application Debugger" contains a debugger (file "Debug") which can be copied into the same folder where a double-clickable application made with MacMETH or RAMSES resides. If the application is halted by an exception (or a so-called user halt - triggered by pressing Command^Option^H simultaneously) you may then debug your application. Hint: To make a folder with the sources accessible, provide also a User.Profile in the folder where the application resides, which is present during start up of the application.

5) "SymDiff", "RenameMany", "MapPackage" are applications, which contain their own "READ.ME" files.

6) The folder "Testing" contains a simple test program to test the "Dialog Machine". If it runs on a particular hardware, operating system combination, you can assume that the "Dialog Machine" supports this particular platform.

7) You can now use the MPW shell to compile and link Modula-2 modules. Use the MPW scripts m2compile and m2link and the standalone tools Compilation and Linking. Detailed instructions and examples are contained in the MPW scripts m2compile and m2link.

8) Some modules are released with several implementations, so called module variants. They may behave differently, e.g. numerically differently, depending on the compiler with which they have been generated or the platform on which they use different system routines. In particular mathematical library modules come in several variants and simulation results may differ, depending which module variant you are using. You find detailed and exhaustive information on this topic at http://www.sysecol.ethz.ch/RAMSES/Documents/README_Module_Variants.txt, where each module variant from the RAMSES/RASS releases is described.

Please consult also the file "On RAMSES (READ ME!)" for general information on RAMSES.

Always download latest updates from http://www.sysecol.ethz.ch, notably the home page of the "RAMSES Extras", i.e. http://www.sysecol.ethz.ch/RAMSES/RAMSES_Extras.html.

Send feedbacks: mailto:RAMSES@env.ethz.ch

Have fun!

Andreas Fischlin - ETH Zurich, Switzerland / 28th September 2006