1: \documentstyle{article}
2: \newcommand{\EcoLab}{{\sffamily\slshape
3: \mbox{\raisebox{.5ex}{Eco}\hspace{-.4em}{\makebox[.5em]{L}ab}}}}
4:
5: \title{\EcoLab: Agent Based Modeling for C++ programmers}
6: \author{Russell K. Standish and Richard Leow\\
7: High Performance Computing Support Unit\\
8: University of New South Wales, Sydney 2052, Australia\\
9: \{R.Standish,R.Leow\}@unsw.edu.au\\
10: http://parallel.hpc.unsw.edu.au/ecolab
11: }
12:
13: \begin{document}
14: \maketitle
15:
16: \begin{abstract}
17: \EcoLab{} is an agent based modeling system for C++ programmers,
18: strongly influenced by the design of Swarm. This paper is just a brief
19: outline of \EcoLab's features, more details can be found in other
20: published articles, documentation and source code from the \EcoLab{} website.
21: \end{abstract}
22:
23: \section{\protect\EcoLab}
24: \EcoLab{} is an ABM system for C++ programmers. This is not the time
25: or place to debate the merits of C++ over any other object oriented
26: language. If you have chosen C++ as an implementation language for
27: your models because of performance, expressibility, familiarity or
28: compatibility with other software libraries, then ABM environments
29: such as Swarm or Repast offer little support to you. In this case, you
30: should consider \EcoLab.
31:
32: \section{Scripting}
33: \EcoLab{} uses the Classdesc\cite{Madina-Standish01} object descriptor
34: technology. This provides a form of object reflection, or the ability
35: to query an object's internal structure at runtime. This may seem
36: obvious to a Java or Objective C programmer, as object reflection is
37: built into the language.
38:
39: How is Classdesc used in \EcoLab{}? The user codes their entire model
40: as a class. Usually, there will only be one instantiated object of
41: that class (the model). Most model instance variables, and model
42: methods adhering to particular calling conventions are exposed to a
43: TCL interpreter. This allows great flexibility to configure different
44: sorts of experiments at runtime. For example, if your model class is:
45: \begin{verbatim}
46: class model_t {
47: public:
48: int tstep; double foo;
49: void step();
50: double average_something();
51: } model;
52: \end{verbatim}
53: then by inserting the macro call \verb+make_model(model)+ into your
54: code, the following TCL script is possible:
55: \begin{verbatim}
56: model.tstep 0
57: model.foo 0
58: while {[model.tstep]<100000} {
59: model.step
60: if {[model.tstep]%1000==0} {puts stdout [model.average_something]}
61: }
62: \end{verbatim}
63: This initialises the instance variables, and runs the model for 100000
64: steps, writing out the average of something every 1000th
65: timestep.
66:
67: \section{GUI mode for exploration}
68:
69: The TCL interpreter also has a complete GUI toolkit (Tk),
70: and a visualisation and analysis toolkit (BLT). It is possible to turn
71: the above script into a continuously updated plot by changing one
72: line:
73: \begin{verbatim}
74: if {[model.tstep]%1000==0} {
75: set av_something [model.average_something]
76: plot av av_something
77: }
78: \end{verbatim}
79:
80: With this ability to script experiments at runtime, one can use one
81: script for exploratory visualisation or debugging, and another for
82: batch production work. Items in common, such as the model's parameters
83: can be stored in a third file and included using TCL's \verb+source+
84: command.
85:
86: The main point is that it is not necessary to be proficient at TCL
87: programming to be productive with \EcoLab. Many example scripts exist
88: in the source code that can be adapted for you use. However, a
89: proficient TCL programmer can exploit a large amount of functionality
90: to create some great visualisations --- using Tk's ability to handle
91: pixmaps for instance. The jellyfish simulation example provided as
92: part of the package is a case in point.
93:
94: \section{Object Browser}
95: Using Classdesc to expose your C++ objects to the TCL environment has
96: some other interesting features. \EcoLab{} comes with an {\em object
97: browser}, which allows the user to drill down into the model to see
98: why a particular object is doing what it is doing. The object browser
99: is \EcoLab's answer to Swarms probes. To use the object browser, just
100: click on the ``Object Browser'' button on the GUI toolbar. This will
101: pop a list of TCL procedures, and top level objects (procedures with ``.'' in
102: their name). Clicking on objects pops up another box containing the
103: procedures within that (corresponding to instance variables and
104: methods) and objects (compound instance variables). Clicking on a
105: procedure will execute that procedure (using any arguments you have
106: provided) and displays the result. You can also arrange to have the
107: procedure executed automatically every second to give a continuous
108: update of (say) and instance variable.
109:
110: \section{Checkpoint/Restart}
111: By invoking Classdesc on your model in this way, TCL commands are
112: created for checkpointing and restarting your model, with no further
113: coding required of your model (provided the complete state of your
114: model is stored in the model object of course). So, if you are using a
115: high performance computing bureau, which forces you to continuously
116: checkpoint and restart your jobs to allow other peoples jobs to run,
117: you can write something like the following TCL script:
118: \begin{verbatim}
119: if [file exists checkpoint] {
120: model.restart checkpoint
121: } else {
122: source model-parms
123: }
124:
125: while {[model.tstep]<100000} {
126: model.step
127: if {[cputime] > 10000} {
128: model.checkpoint checkpoint
129: exit
130: }
131: }
132:
133: if {[model.tstep]<100000} {
134: exec qsub myjob.tcl
135: }
136: \end{verbatim}
137: which is self-submitting batch script in which each job only runs for
138: less that 3 hours, but the chain of jobs continues until the
139: calculation is complete.
140:
141: \section{Parallel Processing}
142:
143: \EcoLab{} provides support for parallel processing using the
144: MPI\cite{mpiref} distributed memory programming model. By turning on
145: the MPI flag at compile time, \EcoLab{} will start an interpreter on
146: each processor. Normally, your script will run on processor 0, but any
147: TCL command can be run on all processors simultaneously with the
148: \verb+parallel+ command. Plus, a method can be declared parallel, so
149: when invoked, it will be invoked on all processors simultaneously.
150: The {\em ClassdescMP}\cite{Standish-Madina03a} can be used to easily
151: code communication between processors, or the full power of MPI used.
152: At this point in time, it is the model implementor's responsibility to
153: arrange for objects to be distributed across the processors, however
154: an experimental project called {\em Graphcode}\cite{Madina02} will
155: allow arbitrary agents on an arbitrary grid topology (graph) to be
156: automatically distributed across parallel processors, even having
157: dynamic updating of the object distribution to optimise load balancing.
158:
159: \section{Supported Machines}
160:
161: \EcoLab{} is an open source project which depends on ANSI standard
162: C++, TCL, Tk and BLT. The primary development environment is Linux,
163: but by its adherence to standards, \EcoLab{} has been successfully
164: ported to Irix, Solaris, AIX, Tru64, Mac OSX and Windows (under
165: Cygwin), often using the native C++ compiler rather than gcc. It
166: should be noted that the Mac OSX port of \EcoLab{} was completed about
167: 6 months ago, and took about 2 days to do, which is one area in which
168: it out competed Swarm. At present the interface depends on X-windows,
169: work on a native Aqua interface is being planned in the next 6 months.
170:
171: \EcoLab{} has now been deployed for 5 distinctly different modelling
172: projects. Each project has its own requirements, which are fed back
173: into the core system where it is useful.
174:
175: There are no plans for a Java interface. The aim of this project is to
176: provide an environment for C++ programmers, not Java programmers who
177: are already catered for with other packages.
178:
179: We welcome contributers to the \EcoLab{} project. The source code is
180: managed by Peter Miller's AEGIS system, so you will need to email
181: Russell Standish to obtain a user login to access AEGIS. Anonymous readonly
182: access to the repository is however already available via the
183: \EcoLab{} website, where you can pick a version of \EcoLab{} at any
184: revision level as a gzipped tarball. Unlike CVS, AEGIS ensures that
185: the code compiles, and that some consistency checks are performed at
186: code check in time. Plus whenever a branch is closed (\EcoLab.4.Dx as
187: opposed to \EcoLab.4.x.Dy), further tests are performed to ensure that
188: the code compiles and runs a test suite on all supported platforms.
189:
190: \section*{Acknowledgments}
191: \EcoLab{} is supported by a generous grant from the {\em Australian
192: Partnership for Advanced Computing} (APAC). Computing resources
193: have been generously provided by
194: {\em Australian Centre for Advanced Computing and Communications}
195: (ac3) for supporting different operating systems and testing
196: parallel programming features.
197:
198: %\bibliographystyle{plain}
199: %\bibliography{rus}
200: \begin{thebibliography}{1}
201:
202: \bibitem{Madina02}
203: Duraid Madina.
204: \newblock Topology and complexity: From automata to agents.
205: \newblock In Namatame et~al., editors, {\em {Complex Systems} '02}, pages
206: 141--147. Chuo University, September 2002.
207: \newblock also to appear in {\em Complexity International}.
208:
209: \bibitem{Madina-Standish01}
210: Duraid Madina and Russell~K. Standish.
211: \newblock A system for reflection in {C++}.
212: \newblock In {\em Proceedings of AUUG2001: Always on and Everywhere}.
213: Australian Unix Users Group, 2001.
214:
215: \bibitem{mpiref}
216: Marc Snir et~al.
217: \newblock {\em MPI: the complete reference}.
218: \newblock MIT Press, Cambridge, MA, 1996.
219:
220: \bibitem{Standish-Madina03a}
221: R.K. Standish and D.~Madina.
222: \newblock {ClassdescMP}: Easy {MPI} programming in {C++}.
223: \newblock In {\em Proceedings of Intennational Conference on Computational
224: Science 2003}, Lecture Notes in Computer Science, Berlin, 2003. Springer.
225: \newblock (accepted).
226:
227: \end{thebibliography}
228:
229: \end{document}
230: