Documentation

• Manuals
• Installation (Mathematica)
• Installation (Matlab)
• Mathematica v6.0 Issues

Manuals

For gory details about the method of calculation, see the following documents:

Suspension Model Comparisons (T020011-00) is a description of comparisons that were made to ensure that the results of the Mathematica models agree (modulo the different aspects of the physics that they incorporate) with the pendulum models in Matlab of Calum Torrie, Ken Strain et al.

Installation

Mathematica Models

toolkit/

PendUtil.nb

PendUtil.m

...

mbquadlite2lateral/

old/

current/

ASUS4L2LateralModelDefn.nb

ASUS4L2LateralModelDefn.m

default/

ASUS4XLLateralModelCalcDefault.nb

precomputed/

anothercase/

ASUS4XLLateralModelCalcAnotherCase.nb

precomputed/

mbtriplelite2lateral/

current/

...

The toolkit directory represents the location where you will put the packages that comprise the pendulum modelling toolkit. It doesn't have to be called toolkit, and you don't have to create a directory for the purpose. If you prefer you can put all the toolkit packages in one of the standard directories on the Mathematica path reserved for custom packages. These differ according to platform and version (see the Mathematica documentation), but for example, on Mac OS X under Mathematica v5+, you have a choice of /Library/Mathematica/Applications and ~/Library/Mathematica/Applications. If you do decide to create a custom directory, you need to specify its name and path in each calculation notebook (see below).

If you download a toolkit package (e.g., PendUtil3.0.zip) from this site what you get is a compressed version of a folder with the .nb and .m files in. Move the individual files to the top level of toolkit and throw away the folder. If you download a master toolkit package archive (e.g., AllPackages20070614.zip), you get an archive of all the most up-to-date individual package archives as of the master archive date. Uncompress the master archive and the nested archives and move all the individual files to the top level of toolkit, throwing away any other folders.

If you download a model archive from this site, what you get is a compressed version of the current directory. Therefore:

1. If you haven't worked with a particular model before, create a top-level directory for it (e.g., mbquadlite2lateral). The exact name is not important as long as it reminds you of what the model is about. Despite what you might expect, this is not what is referred to as "the model directory" in the documentation. The model directory is the one with the model definition file in, i.e., current.
2. If you have worked with a particular model before, rename the existing current directory to old or the like, and unpack the archive of the latest version.
3. Unpack the archive to create a new current directory. This is what is referred to as "the model directory" in all documentation.
4. Go into the default subdirectory and edit the notebook ASUS4XLLateralModelCalcDefault.nb or the like to specify the paths to the toolkit directory and the model directory as explained in the Instructions section of the notebook.
5. Do similarly for any other precomputed cases that may be supplied with the model.
6. If any cases in the old directory are still of interest, move or copy them over to current. If you've worked with them previously, the editing to set paths should still be valid, as long as they're residing in current.

Briefly, the path setting in Step 4 above amounts to:

1. Find what the Mathematica symbol $System evaluates to on your system - it should be a string describing the OS and processor, e.g., "Mac OS X x86 (32-bit)".
2. Find what $Path evaluates to on your system, and note the format of the entries.
3. Find the cell in the calculation notebook that looks like modeldirectory = Switch[$System,

4. "Mac OS X x86 (32-bit)",

   "/Users/mbarton/AdvLIGOModel/mbquadlite2lateral/current"

   ];

5. and edit one of the existing pairs or add a new one to give the location of the model directory as a function of your value of $System in the format of your $Path. (A Switch[] statement may seem like overkill, but it's very convenient if one is using say a Windows laptop in conjunction with a Linux desktop and moving files back and forth or accessing them on a network drive.) Note that Windows paths include backslashes and \ is also the Mathematica string input escape character, so you will need to escape the backslashes , i.e., \ -> \\, even if it doesn't look like that in the output from $Path.
6. Find the cell that looks like

modelsupportdirectory = Switch[

$System,

"Mac OS X x86 (32-bit)","/Users/mbarton/Work/toolkit",

];

and edit it to give the toolkit path as a function of your system.

When you've done the editing you should be able evaluate the calculation notebook from top to bottom without errors. If one of the Switch[] statements gives an error you probably haven't got the system type correct. If the cell that loads the model definition

Get["ASUS4L2LateralModelDefn.m",Path->{Directory[],ParentDirectory[Directory[]]}];

gives an error, you probably haven't got the model directory right. If the cell that opens the status window

OpenStatusWindow[WindowSize->{500,300}];

doesn't produce a window, then you probably haven't got the toolkit directory right.

Matlab Models

Mathematica v6 Issues

• Version 1.1 of the StatusWindow package had a crippling bug under v6 of Mathematica. The status window had been assigned a WindowType of "MoveableModalDialog". Under v4 and v5, this had been synonymous with a "ModelessDialog". Suddenly in v6, it started doing what its name implied: causing the status window to take over the GUI and block access to other windows until dismissed. Unfortunately since no provision for dismissing it had been supplied, this amounted to a fatal lockup. Much less dramatically, some date functions that it used have been deprecated and reintroduced under different names.

FIX: All users should upgrade to StatusWindow v1.2 of 6/14/07. This works in Mathematica v6.0 and is backward compatible to v4.x. As well as fixing the modal dialog issue it also uses the version-appropriate date functions to avoid error messages.

• Several standard packages have been deprecated. In particular, LinearAlgebra`MatrixManipulation`, which supplies functions such as BlockMatrix[] (useful for piecing together state-space matrices) has been deprecated and equivalent functionality doesn't seem to have been added elsewhere. It still seems to work for the purposes of the toolkit, but an annoying warning comes up when it is loaded.

FIX: All users should upgrade to PendUtil v3.0 and MatlabExport v1.3 of 6/14/07. These work in Mathematica v6.0 and are backward compatible to v4.x. PendUtil now adds a reassuring message before loading LinearAlgebra`MatrixManipulation` and avoids loading other deprecated packages (all graphics-related - see below) if $VersionNumber>=6.0. MatlabExport now just avoids loading LinearAlgebra`MatrixManipulation`, which wasn't being used in the package itself in any case.

• In earlier versions of Mathematica, the output from drawing commands happened as a side-effect rather than as a result. The actual result was a non-printing placeholder: "- Graphics -". That meant that if commands were linked in a compound expression using ";", the output would appear no matter where the drawing commands appeared in the list. In Mathematica v6 the output is conceptually the result and so only appears if the drawing command is the last in the chain (and doesn't have a ";" after it). Unfortunately this breaks the following idiom, which has been used countless times throughout the calculation notebooks:

Status["Plotting mode n"];eigenplot[...];Done[];

FIX: Manually edit old calculation notebooks to use one of the following forms:

eigenplot[...] (* if you don't care about the status/timing information *)

DoWithStatus[eigenplot[...]] (* requires StatusWindow v1.2 *)

Status["Plotting mode"];tmp=eigenplot[...];Done[];tmp (* doesn't require v1.2 *)

Transfer function and thermal noise plots need the same treatment. This will be done for all newly released models/cases but there are so many instances that it won't be feasible to rerelease everything.

• The facilities for drawing 3D objects have been extensively revised, with several packages obsoleted and many functions renamed and/or modified. Unfortunately this will require a total rewrite of the bits of the eigenplot[] function that draw the hanging masses, for every different model.

FIX: Apply all the 6/14/07 toolkit updates. That will let you muddle through using all the model features except eigenmode plots. Then wait for an updated release of the model you're interested in. Or hassle the author. Or update it yourself, following the pattern of the Quad Xtra-Lite Lateral model v5.0 of 6/16/07.

Of course, Mathematica v6 does have some nice features. In particular the new Animate[] function makes it trivial to do animations of mode shapes. For example, in the Quad Xtra-Lite Lateral model, try:

Animate[eigenplot[eigenvectors2[[-1]], 0.3*Sin[t], {0, -1, 0}, floatmatrix2], {t, 0, 2 Pi}]