Berkeley Madonna User’s Guide

Berkeley Madonna User’s GuideVersion 8.0April 21, 2003Robert MaceyGeorge OsterTim ZahnleyUniversity of CaliforniaDepartment of Molecular and Cellular BiologyBerkeley, CA 94720http://www.berkeleymadonna.com

Table of ContentsINTRODUCTION .5SYSTEM REQUIREMENTS.5BERKELEY MADONNA WINDOWS.5THE EQUATION WINDOW.5THE FLOWCHART WINDOW.7THE PARAMETER WINDOW .8THE GRAPH WINDOW .9Creating Multiple Graph Windows.9Specifying Which Variables to View .9Changing Axis Settings .10Creating Multiple Pages [Windows only] .11Using Graph Buttons .11Printing Graphs and Tables.13Exporting Graphs and Tables.13Customizing Background Colors [Macintosh only] .13Oscilloscope Mode .13Run Information.14Readout.14Initial Conditions.14Fast-Fourier Transform .15THE DATASETS WINDOW .15Importing Datasets .15Vector Datasets.16Matrix Datasets .16Modifying and Removing Datasets.16THE NOTES WINDOW.17Embedding Pictures and Objects .17RUNNING MODELS .17SINGLE RUN .17CONTINUE RUN [WINDOWS ONLY].18SLIDERS .18BATCH RUNS .19PARAMETER PLOT .19CHECK DT.21FLOATING-POINT EXCEPTIONS .21EQUATION SYNTAX.22BASIC SYNTAX .22DIFFERENTIAL EQUATIONS .23DIFFERENCE EQUATIONS .24DISCRETE EQUATIONS .24Conveyors .25Ovens.25-2-

Queues.27ROOT FINDER EQUATIONS .28Initial and Step Root Finders .28The Root Finder Algorithm .29Multidimensional Root Finders .29LIMIT EQUATIONS .30OTHER EQUATION TYPES.30METHOD Statement .30DISPLAY Statement.30RENAME Statement.31BUILT-IN SYMBOLS .31OPERATORS .32BUILT-IN FUNCTIONS .33ARRAYSUM, ARRAYMEAN, ARRAYSTDDEV .35BINOMIAL, NORMAL, POISSON, RANDOM.35DELAY .35NETFLOW.35STEPSIZE.36MAXINFLOW, OUTFLOW, OSTATE, QPOP, QPOPS .36ARRAY EQUATIONS.36DATASET FUNCTIONS .39Plotting Matrix Datasets .39REGIONAL SETTINGS [WINDOWS ONLY].40RUNNING STELLA MODELS .40TIPS AND TECHNIQUES .41Creating Periodic Functions .41Creating Piecewise-Linear Functions.42Non-negative Reservoirs and Unidirectional Flows.42Simulating STELLA Conveyors, Ovens, and Queues .43INTEGRATION METHODS.43FIXED-STEPSIZE METHODS .43VARIABLE-STEPSIZE METHODS .44USING DTOUT .45CUSTOM DT METHOD .46OTHER FEATURES .47CHEMICAL REACTIONS .47Adding Other Equations .49CURVE FITTER .50Multiple Fits .51Specifying Initial Guesses .51Floating-point Exceptions .51OPTIMIZER .51BOUNDARY VALUE SOLVER .52SENSITIVITY .53PLUG-IN FUNCTIONS AND INTEGRATION METHODS .54-3-

FLOWCHART REFERENCE .54ALIASES .54SUBMODELS .55Creating and Deleting Submodels.56Making Connections Between Submodels .56Moving Icons Between Submodels .58FLOWCHART TOOLBAR.58FLOWCHART COMMANDS .61FLOWCHART PREFERENCES .63CUSTOMIZING ICONS .64KNOWN BUGS AND LIMITATIONS .65-4-

IntroductionBerkeley Madonna is a program that numerically solves systems of ordinary differentialequations (ODEs) and difference equations. It was originally developed to execute modelswritten in STELLA more quickly. Over time, we added our own unique features which havemade Berkeley Madonna into a fast, self-contained, and easy-to-use modeling tool.Berkeley Madonna is available for both Macintosh and Windows platforms. While theseversions are mostly identical, there are some differences which are noted throughout thisguide with the notation [Macintosh] or [Windows].System RequirementsMacintosh: Power Macintosh or compatible computer1 with a PowerPC processor and leasttwo megabytes of free memory. It may require more memory depending on the size of yourmodels and the amount of data they generate. The flowchart editor requires MRJ 2.1 or later tobe installed on your system.2 You can download the latest version of MRJ fromhttp://www.apple.com/java. Note that Mac OS 9 comes with MRJ 2.1.4. We recommend thatyou use MRJ 2.2 or later since it offers significantly improved performance over MRJ 2.1.x.Windows: PC compatible running Microsoft Windows 95 or later, or Windows NT 4.0 or later.It does not work under older versions of Windows NT (such as 3.51), nor does it run under 16bit versions of Windows (3.1, 3.11, etc) .3 The flowchart editor required JRE 1.1 to be installedon your system.4 You can download the latest version of JRE 1.1 ley Madonna WindowsBerkeley Madonna uses various kinds of windows to represent your model includingequation, flowchart, parameter, graph, datasets, and notes windows.The Equation WindowYou use the equation window to edit your model’s equations. The editor is a simple plain texteditor similar to SimpleText [Macintosh] or Notepad [Windows]. The equation window can bedisplayed at any time by choosing Equations from the Model menu.When you create a new model using the New command in the File menu, Berkeley Madonnacreates a new, untitled equation window. Similarly, when you open a plain text file, it creates anew, untitled equation window showing the file’s contents.1Berkeley Madonna does not run on “classic” Macintosh models with 68K processors.2MRJ stands for Macintosh Runtime for Java.3It may be possible to run Berkeley Madonna on Windows 3.1 or 3.11 by first installing Microsoft’s Win32s extensions. However, this has notbeen tested and is not supported.4JRE stands for Java Runtime Environment.-5-

You don’t need to keep the equation window open if you don’t want to. As long as at least oneother window for your model is open (parameters, graphs, etc.), you can close the equationwindow and your model will remain open.Changes made to your equations do not take effect until your model has been recompiled. Bydefault, Berkeley Madonna automatically recompiles your equations when you perform any ofthe following operations:Model menu:Modules » Boundary Value ODERunCompute menu:Check DT/TOLERANCERunGraph menu:New GraphChoose VariablesParameters menu:Parameter WindowDefine SlidersShow SlidersBatch RunsRepeat Batch RunsCurve FitOptimizeParameter PlotSensitivityHowever, if you turn off the Automatically Recompile Equations option in the General pageof the Preferences dialog, Berkeley Madonna will only recompile your changed equationswhen you explicitly tell it to do so by choosing Compile from the Model or Compute menus.By default, Berkeley Madonna will prompt you before recompiling the equations. This givesyou the opportunity to either cancel the recompile operation or revert to the equations thatwere last compiled. You can avoid this prompting by turning off the Confirm BeforeRecompiling Equations option in the General page of the Preferences dialog.When Berkeley Madonna recompiles your equations, all runs in memory are discarded. Inaddition, any settings in your model that depend on particular symbol names (such as-6-

variables in graph windows, modified parameter values, sliders, etc.) will be lost if youchanged the name of the symbol in your equations.If Berkeley Madonna finds an error when compiling your equations, an error message isdisplayed and the suspect text will be selected in the equation window. The Equation Syntaxsection on page 22 explains how to write properly-formed equations.The equation window supports several editing features of note: Standard clipboard commands (cut/copy/paste) and drag-drop editing are provided. Text that would extend past the right edge of the window is automatically wrapped to thenext line; there is no need for a horizontal scroll bar and Berkeley Madonna doesn’tprovide one. The Balance command in the Edit menu selects the text within the innermost matchingpair of parentheses or brackets. The search for a matching pair of characters starts at thecurrent insertion point or selection and expands outward. This feature helps you to locatesub-expressions nested within complex equations. The Find and Replace commands in the Edit menu help you search for and replacetext in your equations. The Settings dialog (Model menu) allows you to change the font used to display yourmodel’s equations. This font is also used for axis labels in your model’s graph windows. The Save Equations As command in the File menu allows you to save your model’sequations as a plain text file. This is useful for transferring your equations to anotherprogram. Note that this command is available only when an equation window is active. The Print Equations command in the File menu allows you to print your model’sequations on the current printer. You may want to use the Print Preview command first toverify that the margins are appropriate and to determine how many pages would berequired to print them. This command is available only when an equation window isactive. The Insert Picture [Macintosh] or Insert Object [Windows] command allows you to embedpictures and objects within your equations. See Embedding Pictures and Objects on page17. Note that embedded objects are treated by the compiler as if they were blanks (spacecharacters). Therefore, they have no effect on the semantics of your model’s equations.By default, newly created models use the Geneva 12 [Macintosh] or Arial 10 [Windows] fontfor their equations. You can change this default in the General page of the Preferences dialog.The Flowchart WindowThe flowchart window provides an alternative to the equation window for constructingmodels. Instead of typing in equations by hand, you build models by dragging icons from atoolbar onto a flowchart and connecting them with arcs to represent dependencies. As youconstruct your model graphically, Berkeley Madonna generates textual equations representingyour model’s structure.To create a new visual model, choose New Flowchart from the File menu. This opens anempty flowchart window on which you construct your model. Unlike plain-text models(created with the New command), a visual model’s equations cannot be edited directly in the-7-

equation window. Instead, equations are edited within each icon’s “icon dialog” which isopened by double-clicking the icon.The flowchart window can be hidden by choosing Hide Flowchart from the Flowchart menu.This can be done as long as some other non-flowchart window for this model is open (such asa graph window or the equation window). The command then changes to Show Flowchartwhich makes the flowchart window visible again.Visual models can be converted into plain-text models by choosing Discard Flowchart fromthe Flowchart or Model menus. After discarding the flowchart, the model’s equations can beedited directly in the equation window. Use caution as the flowchart cannot be recovered ifyou save a model after its flowchart has been discarded.Berkeley Madonna cannot convert plain-text models into visual models for you. However, youcan create a new visual model that duplicates the behavior of an existing plain-text model.Refer to “Building a Visual Model” in the Berkeley Madonna Tutorial to familiarize yourself withbasic techniques for constructing and editing visual models. After you’re comfortable with thebasics, refer to the Flowchart Reference on page 54 to learn about more sophisticated flowchartfeatures.The Parameter WindowYou can display the parameter window by choosing Parameter Window from the Parametersmenu. This window allows you to change parameters in your model as well as the integrationmethod5 without recompiling your model.Parameters are symbols whose values do not depend on any other symbols in your model anddo not change over time. Berkeley Madonna define

Berkeley Madonna is available for both Macintosh and Windows platforms. While these versions are mostly identical, there are some differences which are noted throughout this guide with the notation [Macintosh] or [Windows]. System Requirements Macintosh: Power Macintosh or compatible computer1 with a PowerPC processor and least