[idmc commit] r46 - wiki
codesite...@google.com
Date: Fri Jul 6 05:09:11 2007
New Revision: 46
Added:
wiki/DevelopersNotes.wiki
Log:
Created wiki page through web user interface.
Added: wiki/DevelopersNotes.wiki
==============================================================================
--- (empty file)
+++ wiki/DevelopersNotes.wiki Fri Jul 6 05:09:11 2007
@@ -0,0 +1,149 @@
+#summary Overall structure and how to modify the source code
+
+In what follows we provide detailed information regarding the
+iDMC software program source code: the overall structure; how it
+works; how to run it; how to compile and modify it (under both
+Windows and Linux operating systems)
+
+=The overall structure=
+
+iDMC is composed of the following parts: a Java part, which is
+responsible for the user interface in the broad sense; a C part
+which is responsible for making the computations; a Lua part which
+consists of .lua files describing the dynamical systems.
+
+.lua files get compiled and run at run-time by C functions which
+acquire this ability by using special purpose C libraries,
+written by Lua language authors. The C functions sit in a dynamically
+linked library (.dll), and get called by Java classes using the JNI
+interface API (a standard Java library).
+Below only the Java part is described.
+
+The Java part of iDMC is organized into numerous packages. The packages
+form a tree like structure, just as the usual tree of directories.
+The main five packages (four of which are subpackages of the firs
+t package) are:
+
+# org.tsho.dmc2:
+this is the "root" package. In it sits the class DmcDue, whose
+main() method is the actual body of the program.
+
+# org.tsho.dmc2.ui:
+this package and its subpackages contain the
+basic user interface classes of DMC. Among these (here and below
+we omit the classes fully qualified names, i.e. instead of writing
+org.tsho.dmc2.ui.MainFrame, we write just MainFrame) are the
+classes MainFrame, MainFrameSM, AbstractPlotComponent,
+AbstractControlForm and others. It contains the subpackages:
+org.tsho.dmc2.ui.lyapunov org.tsho.dmc2.ui.trajectory
+org.tsho.dmc2.ui.manifolds org.tsho.dmc2.ui.basin and
+others. For the most part, these packages contain the subclasses
+of AbstractControlForm, StateMachine (see below) and
+AbstractPltComponent which are adapted to the corresponding task
+at hand.
+
+# org.tsho.dmc2.sm:
+contains the state machine classes and other auxiliary classes.
+Main classes here are:
+StateMachine and its subclass ComponentStateMachine.
+
+# org.tsho.dmc2.managers:
+contains the AbstractManager class and its
+various subclasses adapted to the task at hand (e.g.
+TrajectoryManager, BasinManager etc.) These classes manage the
+data input and the generation of corresponding plots.
+
+# org.tsho.dmc2.core:
+this package is responsible for all the
+remaining duties, such as actually performing the computations
+(the classes of the org.tsho.dmc2.core.dlua subpackage), and
+drawing the plot (the classes of the org.tsho.dmc2.chart
+subpackage). Other packages include classes which are responsible
+for ODE Lyapunov exponents algorithm, some utility classes
+etc.
+
+*Important Note*
+
+Another key class is org.tsho.dmc2.core.chart.jfree.DmcChartPanel.
+Its role is to modify the functionality of an analogous class
+called ChartPanel)in JFreeChart, the graphical library used by iDMC.
+Using ChartPanel instead of DmcChartPanel would drastically degrade the
+program performance, since every time the program window is
+resized, ChartPanel recomputes the position of all the data points
+(so that the data will fit in the resized window). In the iDMC
+setting this is unacceptable because when the data consists of
+tens of thousands of data points (typical sitiation in iDMC) this
+recomputation appears to require tens of seconds. DmcChartPanel
+fixes this problem.
+
+=How the program functions, a very rough sketch=
+
+The main() method of DmcDue constructs a MainFrame Instance with
+which the state machine MainFrameSM instance, constructed at the
+same time, gets associated. This is the window one sees
+immediately after double clicking the program's icon. The
+MainFrameSM state machine controls the succesion of events so that
+pressing the buttons and choosing menu items in any combination
+will lead to meaningful results.
+
+When a model is chosen, an info panel ( subclass of Swing's
+JPanel) is put to a JTabbedPane instance, itself a subcomponent of
+the MainFrame instance. Choosing from the menu a Plot type
+(trajectory plot, or basin plot, etc.) causes the corresponding
+subclass of AbstractPlotComponent (TrajectoryComponent, or
+BasinComponent, etc.) to be constructed and put inside the
+JTabbedPane instance.
+
+Simultaneously, instances of the corresponding subclasses of
+AbstractManager, StateMachine and AbstractControlForm, of the
+corresponding renderer class, and of DmcChartPanel are constructed
+and associated with the plot component. Then, for example, the
+trajectory plot instances of the classes TrajectoryManager,
+TrajectoryRenderer, TrajectorySM, TrajectoryControlForm2 and
+DmcChartPanel are constructed and associated with the
+TrajectoryComponent instance. TrajectoryManager is aided by
+TrajectorySM to control the actions resulting from pressing
+buttons and making menu choices, while TrajectoryRenderer makes
+the actual trajectory plot and the drawing is done on the
+DmcChartPanel.
+
+=How to run, compile and modify iDMC on the Windows
+operating system =
+
+Download the iDMC _source_ package and unpack it.
+Here you will find a COMPILING file with up-to-date compiling istructions.
+
+The folder iDmc-2.x.x has the subfolders (among others):
+doc, misc, models, src/java. The src/java folder contains the Java source code.
+Suppose we wish to build the executable .jar file of iDMC
+(either because we wish to build the program from scratch,
+or because we have modified the Java source code
+and wish to build a new executable .jar file).
+
+Open the DOS shell (as indicated above), and go to the directory
+iDMC-1.9.2 (which is a subdirectory of iDMC-1.9.2-src).
+Now type in "ant" in the DOS shell. If Ant was installed
+correctly (i.e. the necessary environment variables are set to the
+required values), this would create a new executable .jar file
+in the iDMC-1.9.2 subfolder of iDMC-1.9.2-src
+(assuming there have not been any compilation time errors).
+
+If you have downloaded already the binary code folder of iDMC,
+you may test the new .jar file by replacing the .jar file in the
+
+iDMC-1.9.2-bin directory with the one which was
+just created and double clicking it as usual
+(or typing in java -jar <filename.jar> from the DOS shell
+command line).
+
+REMARK Ant compiles only the source (.java) files whose time stamp
+is more recent than the time stamp of the corresponding object (.class)
+files (this is done to reduce the compilation time). Thus, if you replace
+a source code file with a one which carries the same name, but an earlier
+time stamp (e.g. a previous backup version), the source code will compile properly, only if you first delete the corresponding
+.class file. To ensure that all the source code is compiled anew, first
+type in (in the DOS shell) "ant all-clean", and then type in "ant".
+
+=Modifying and compiling the native C part=
+The native code used by iDMC is all contained in the idmclib library.
+See its boundled docs for up-to-date informations.