Free cookie consent management tool by TermsFeed Policy Generator

source: branches/OKBJavaConnector/ECJClient/src/ec/util/README @ 6934

Last change on this file since 6934 was 6152, checked in by bfarka, 14 years ago

added ecj and custom statistics to communicate with the okb services #1441

File size: 6.4 KB
Line 
1This package contains auxillary utility classes and functions used by ECJ, but
2which can easily be used by other Java libraries and are not specific to ECJ.
3
4
5LOGGING FACILITY
6----------------
7
8When ECJ was first developed (in 1998) there was no Java logging facility, no
9log4j, etc.  So I rolled my own, largely a copy of the one in lil-gp.  The
10facility has proven fairly robust, so we've kept it over the years.  The
11facility has a basic class:
12
13  ec.util.Output
14
15... which does most of the logging work.  Output holds one or more *logs*,
16defined by
17
18  ec.util.Log
19
20... which are largely (but not required to be) wrappers around streams to
21standard out, standard err, or various files.  Output then allows you to print
22to these logs, or to issue "announcements" to them.  An announcement is
23different from an ordinary print statement in that it is also stored in memory
24permanently, and so gets checkpointed.  When a log is restarted from
25checkpoint, all of its announcements can be reissued to the log; that's how
26ECJ prints all of its stuff out to the terminal again when restarting from
27checkpoint.  Beware that because announcements are stored in memory as well as
28printed out, if you issue too many of them, you'll fill up memory excessively.
29Announcements are all subclasses
30
31  ec.util.Announcement
32
33Logs restart themselves from checkpoint using a small class:
34
35  ec.util.LogRestarter
36
37When output generates exceptions, usually pertaining to writing to Logs, it
38does so with an OutputException
39
40  ec.util.OutputExcption
41
42
43
44RANDOM NUMBER GENERATORS
45------------------------
46
47ECJ's random number generator is a Java implementation of the Mersenne Twister
48random number generator which I wrote in 1998.  It's still a popular
49implementation of the Mersenne Twister algorithm, largely because it's quite
50fast.  ECJ has two versions of the algorithm but only uses one:
51MersenneTwisterFast:
52
53  ec.util.MersenneTwister
54 
55  A drop-in subclass replacement for java.util.Random which uses the
56  Mersenne Twister algorithm instead.
57
58  ec.util.MersenneTwisterFast
59
60  Algorithmically identical to ec.util.MersenneTwister, but without
61  synchronization, and with a lot of hard-code-inlined methods.  As
62  a result much harder to read and understand, but over twice as fast.
63
64
65PARAMETER DATABASE 
66------------------
67
68ECJ's parameter database facility was also built from scratch at a time when
69Java had no other built-in facilities available.  The parameter database is
70built on top of Java's Properties class, but adds the additional functionality
71of multiple files with inheritance, plus command-line properties and dynamic
72properties.  The primary class is
73
74  ec.util.ParameterDatabase
75
76... which loads properties from various files and stores them internally for
77you to query at runtime.  To query for a property, you create a Parameter
78(a wrapper for String, used instead of String for entirely historical reasons).
79You then issue the Parameter to the ParameterDatabase and get the corresponding
80value.  Parameters are defined with:
81
82  ec.util.Parameter
83
84When there is an exception upon creating a Parameter, a BadParameterException
85is thrown:
86
87  ec.util.BadParameterException
88
89When you use a Parameter to attempt to load and and initialize a class from
90the ParameterDatabase, and something failed on that attempt, a
91ParamClassLoadException is called:
92
93  ec.util.ParamClassLoadException
94
95The GUI facility of ECJ has additional classes meant to access parameters
96programmatically in Swing.  Generally you wouldn't play with these:
97
98  ec.util.ParameterDatabaseEvent
99  ec.util.ParameterDatabaseTreeModel
100  ec.util.ParameterDatabaseTreeNode
101  ec.util.ReflectedObject
102
103
104
105READING, WRITING, CHECKPOINTING, AND NETWORKING
106-----------------------------------------------
107
108Many ECJ objects (notably Individuals) have the ability to write themselves
109out to a stream in a fashion that is both readable by humans (more or less)
110*and* can be read back in a way that maintains integrity.  To do this they
111rely on ECJ's "Code" facility to encode and decode basic data elements.  To
112encode data, you can use the Code class:
113
114  ec.util.Code
115
116To decode data, you use the Code class in conjunction with a special object
117which gives you additional information about the decoded data.  This special
118object is called a DecodeReturn:
119
120  ec.util.DecodeReturn
121
122In certain rare situations ECJ finds that it needs to be able to hook a
123DataOutputStream directly to a DataInputStream.  Surprisingly, Java cannot
124provide this facility without using two threads (to enable the PipedInputStream
125and PipedOutputStream).  ECJ's solution is a buffered single-thread pipe called
126DataPipe:
127
128  ec.util.DataPipe
129
130ECJ implements checkpointing of runs via Java's serialization facility.  The
131cover class which handles this work is called Checkpoint:
132
133  ec.util.Checkpoint
134
135Last, a long-standing bug in Java prevents proper lookup of localhost sockets.
136This is fixed using a class from Jakarta called LocalHost:
137
138  ec.util.LocalHost
139
140
141
142MANIPULATING ARRAYS
143-------------------
144
145Largely for historical reasons, ECJ has its own quicksort facilities.  We keep
146these facilities because, quite surprisingly, Java's current sorting facilities
147are very much insufficient.  ECJ's basic class for sorting is QuickSort:
148
149  ec.util.QuickSort
150
151QuickSort relies on a special Comparator object for determining whether two
152objects are greater or less than one another.  This is mostly for historical
153reasons.  There is also a special version of this object for longs:
154
155  ec.util.SortComparator
156  ec.util.SortComparatorL
157
158ECJ can convert arrays of floats, doubles, or arbitrary objects, into
159distributions and then select random numbers under them (treating the
160values in the arrays as actual prenormalized probabilities).  The primary class
161for this is RandomChoice:
162
163  ec.util.RandomChoice
164
165RandomChoice can work with arrays of Objects as long as there's a provided
166object a RandomChoiceChooser, which provides the "probability" value for a
167given Object.  There are two versions of RandomChoiceChooser, one which
168assumes probabilities are floats, and the other which assumes they are doubles
169(again, mostly for historical reasons):
170
171  ec.util.RandomChoiceChooser
172  ec.util.RandomChoiceChooserD
173
174
175
176SIMPLE LEXING (TOKENIZING)
177--------------------------
178
179ECJ's Grammatical Evolution facility needs to lex simple rulesets, one per line,
180from a file.  The following class makes regular-expression-based lexing simpler:
181
182  ec.util.Lexer
183
184
185
186ECJ'S VERSION
187-------------
188
189Information regarding the current version of ECJ is located in:
190
191  ec.util.Version
Note: See TracBrowser for help on using the repository browser.