Skip to content

Commit d9eb633

Browse files
ctjoreillyctjoreilly
authored
Merge pull request aimacode#251 from sebkur/convert-readmes
Convert aima-core README to markdown.
2 parents b1df705 + b80c8bf commit d9eb633

File tree

2 files changed

+312
-295
lines changed

2 files changed

+312
-295
lines changed

‎aima-core/README.md‎

Lines changed: 312 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,312 @@
1+
# AIMA-CORE
2+
3+
### Requirements
4+
JDK 1.8 - is the baseline JDK against which this project is developed.
5+
6+
### Current Release: 3.0.0-Search-Improvements
7+
#### 3.0.0-Search-Improvements : Dec 18 2016
8+
* Releasing as a full version number, corresponding to 3rd edition of book
9+
(i.e. all 3rd edition releases will start with 3.x.x going forward).
10+
11+
## Details
12+
13+
### Build Instructions
14+
If you just want to use the classes, all you need to do is put the aima-core.jar on your CLASSPATH.
15+
16+
If you want to rebuild from the source, run the unit tests etc.., follow these instructions:
17+
18+
To build from the command line:
19+
* Ensure you have [ant](http://ant.apache.org/) installed.
20+
* Download the release archive.
21+
* Unzip
22+
* Go to the aima-core directory
23+
* Type 'ant'. This will generate a build directory, which will include the following sub-directories:
24+
* bin/ will contain all the main and test Java classes.
25+
* doc/ will contain generated JavaDoc for the project.
26+
* release/ will contain a jar file of all the core algorithms.
27+
28+
Note: Many IDE's have built in ant versions. So you may want to try that first.
29+
Included in the aima-core directory are .classpath and .project files for the [Eclipse](http://www.eclipse.org Eclipse) IDE.
30+
31+
## Using the Code
32+
33+
For examples of how to use the various algorithms and supporting classes, look at the test cases in the parallel directory structure under src/test.
34+
35+
36+
### Notes on Search
37+
38+
To solve a problem with (non CSP) Search you need to write five classes:
39+
* a class that represents the Problem state. This class is independent of
40+
the framework and does NOT need to subclass anything.
41+
Let us, for the rest of these instruction, assume you are going to solve
42+
the NQueens problem. So in this step you need to write something like
43+
`aima.core.environment.nqueens.NQueensBoard`.
44+
* an implementation of the `aima.core.search.framework.GoalTest` interface.
45+
This implements only a single function — `boolean isGoalState(Object state);`
46+
The parameter state is an instance of the class you created in step 1-a
47+
above. For the NQueensProblem you would need to write something like
48+
`aima.core.environment.nqueens.NQueensGoalTest`.
49+
* an implementation of the `aima.core.search.framework.ActionsFunction`
50+
interface. This generates the allowable actions from a particular state.
51+
An example is
52+
`aima.core.environment.nqueens.NQueensFunctionFactory.NQActionsFunction`.
53+
* an implementation of the `aima.core.search.framework.ResultFunction`
54+
interface. This generates the state that results from doing action a in a
55+
state. An example is
56+
`aima.core.environment.nqueens.NQueensFunctionFactory.NQResultFunction`.
57+
* if you need to do an informed search, you should create a fourth class
58+
which implements the `aima.core.search.framework.HeuristicFunction`.
59+
For the NQueens problem, you need to write something like
60+
`aima.core.environment.nqueens.QueensToBePlacedHeuristic`.
61+
62+
that is all you need to do (unless you plan to write a different search than is available in the code base).
63+
64+
To actually search you need to
65+
* configure a problem instance
66+
* select a search. Configure this with Tree Search or GraphSearch if applicable.
67+
* instantiate a SearchAgent and
68+
* print any actions and metrics
69+
70+
A good example (from the NQueens Demo) is:
71+
```java
72+
private static void nQueensWithBreadthFirstSearch() {
73+
try {
74+
System.out.println("\nNQueensDemo BFS -->");
75+
Problem problem = new Problem(new NQueensBoard(boardSize), NQueensFunctionFactory.getIActionsFunction(),
76+
NQueensFunctionFactory.getResultFunction(), new NQueensGoalTest());
77+
SearchForActions search = new BreadthFirstSearch(new TreeSearch());
78+
SearchAgent agent = new SearchAgent(problem, search);
79+
printActions(agent.getActions());
80+
printInstrumentation(agent.getInstrumentation());
81+
} catch (Exception e) {
82+
e.printStackTrace();
83+
}
84+
}
85+
```
86+
87+
For further information about code design, see the [Wiki](https://github.com/aimacode/aima-java/wiki).
88+
89+
### Logic Notes
90+
To use First Order Logic, first you need to create an instance of `aima.core.logic.fol.domain.FOLDomain`
91+
which collects the FOL Constants, Prredicates, and Function etc... that you use to solve a particular problem.
92+
93+
A parser (that understands the Grammar in figure 8.3 (page 293 of AIMA3e) needs to be instantiated with this domain, e.g:
94+
95+
FOLDomain weaponsDomain = DomainFactory.weaponsDomain();
96+
FOLParser parser = new FOLParser(weaponsDomain);
97+
98+
the basic design of all the logic code is that the parser creates a Composite (Design Patterns by Gamma, et al) parse tree over which various Visitors (Design Patterns by Gamma, et al) traverse. The key difference between the Visitor elucidated in the GOF book and the code is that in the former the visit() methods have a void visit(ConcreteNode) signature while the visitors used in the logic code have a Object visit(ConcreteNode,Object arg) signature. This makes testing easier and allows some recursive code that is hard with the former .
99+
100+
101+
### Probability Notes
102+
103+
I have tried to make the code stick very closely to Dr. Norvig's pseudo-code. Looking at the tests will reveal how to use the code.
104+
105+
106+
### LearningNotes
107+
108+
#### Main Classes and responsibilities
109+
A <DataSet> is a collection of <Example>s. Wherever you see "examples" in plural in the text, the code uses a DataSet. This makes it easy to aggregate operations that work on collections of examples in one place.
110+
111+
An Example is a collection of Attributes. Each example is a data point for Supervised Learning.
112+
113+
DataSetSpecification and AttributeSpecification do some error checking on the attributes when they are read in from a file or string. At present there are two types of Attributes - A sring attribute, used for datasets like "restaurant" and a Numeric Attribute, which represents attributes which are numbers. These are presently modeled as Doubles.
114+
115+
A Numerizer specifies how a particular DataSet's examples may be converted to Lists of Doubles so they can be used in Neural Networks. There is presently one numerizer in the codebase (IrisDataSetNumerizer) but it is trivial to write more by implementing the Numerizer interface.
116+
117+
#### How to Apply Learners
118+
119+
The DecisionTreeLearner and DecisionListLearner work only on datasets with ordinal attributes (no numbers). Numbers are treated as distinct strings.
120+
121+
The Perceptron and DecisionTreeLearners work on *numerized datasets*. If you intend to work with these, you need to write a DataSetSpecific Numerizer by implementing the Numerizer interface.
122+
123+
1. To import a dataset into a system so that learners can be applied to it, first add a public static DataSet getXDataSet(where "x" is the name of the DataSet you want to import) to the DataSetFactory
124+
125+
2. Learners all implement the Learner interface with 3 methods, train, predict and test. If you want to add a new type of Learner (a partitioning Decision Tree learner perhaps?) you need to implement this interface.
126+
127+
## Change History (Update in reverse chronological order)
128+
#### 0.12.0-Search-Improvements : Dec 18 2016
129+
* Improvements/Simplifications across search related APIs.
130+
* Complete set of algorithms for Chapters 22, 23 and 25 added.
131+
* Moved from JDK-7 to 8 as the baseline for further development.
132+
133+
#### 0.11.1-Chp7-Complete : Mar 15 2015
134+
* Fixed Issue 33, Add implementation of - Fig 7.22 SATPlan
135+
* Improved performance of DPLL implementation and added an alternative implementation that uses a couple
136+
of trivial optimizations to improve performance by about 40% over the default DPLL implementation
137+
that matches the description in the book.
138+
* New DPLL interface added to allow people to experiment with different implementations in order to try
139+
out performance enhancement ideas from the book and other sources.
140+
* Added tests for and corrected defects found in the HybridWumpusAgent and WumpusKnowledgeBase implementations.
141+
142+
#### 0.11.0-Chp7-Rewrite : 10 Aug 2014
143+
* Rewrite of the algorithms in Chapter 7 to more closely map to pseudo-code
144+
in book and to resolve outstanding issues.
145+
* Baseline JDK supported by this library has been moved up from 1.6 to 1.7.
146+
* Upgraded JUnit from 4.7 to 4.11.
147+
* General Lexer and Parser Improvements:
148+
* Tokens now track the position in the input that they started at.
149+
* More informative Lexer and Parser exceptions are now generated.
150+
Intended to help with identifying in the input where an error occurred.
151+
* Propositional Parser Improvements:
152+
* Takes operator precedence into account (i.e. does not require concrete syntax to be fully bracketed).
153+
* Abstract syntax to Concrete syntax (ie. toString) only outputs brackets when necessary (easier to read)
154+
so concrete syntax can be parsed back in again unchanged.
155+
* Square brackets can be used in addition to parenthesis to explicitly indicate precedence.
156+
* Symbols changed for the following logical connectives:
157+
* not -> ~
158+
* and -> &
159+
* or -> |
160+
* Abstract syntax tree (i.e. Sentence) simplified to correspond more closely with description in book.
161+
* FOL Clause synchronization and performance enhancements contributed by Tobias Barth.
162+
* Fixed Issue 31, Add implementation of - Fig 7.1 KB-Agent
163+
* Fixed Issue 32, Add implementation of - Fig 7.20 Hybrid-Wumpus-Agent
164+
* Fixed Issue 72, Propositional CNF parsing issue.
165+
* Fixed Issue 78, Propositional CNFTransformer fails to transform Sentence.
166+
* Fixed Issue 79, Random/False Bug in AIMA WalkSAT.java
167+
* Fixed Issue 80, small bug in XYLocation.hashCode()
168+
* Fixed Issue 83, Wrong time variable used in WumpusWorldKnowledgeBase.java
169+
* Improvements and defect fixes to CSP logic.
170+
171+
#### 0.10.5-Chp4-Rewrite : 09 Oct 2012
172+
* Implemented AND-OR-GRAPH-SEARCH from Chapter 4 (completing the set of algorithms from this chapter).
173+
* Fixed Issue 65, Improve genetic algorithm implementation, rewritten to be easier to use/extend.
174+
* Fixed Issue 73, misplaced tile heuristic function no longer counts the gap.
175+
* Fixed Issue 74, defect in implementation of genetic algorithm, fixed indirectly due to Issue 65 re-implementation.
176+
* Fixed Issue 76, QLearning Agent corrected to know which actions are possible in which states.
177+
* Fixed Issue 77, valid hashCode() method missing on TicTacToeState.
178+
* Minor documentation and code cleanup.
179+
180+
#### 0.10.4-Chp5-Rewrite : 08 Jan 2012
181+
* Redesigned and re-implemented adversarial search algorithms from Chapter 5.
182+
* Rewrote Minimax-Decision and Alpha-Beta-Search algorithms.
183+
* Redesigned Game interface to more closely reflect that as described in AIMA3e.
184+
* Added Minimax search with alpha-beta pruning and action ordering (IterativeDeepeningAlphaBetaSearch.java).
185+
* Updated environment definitions/classes for Tic-Tac-Toe game.
186+
* Added environment definitions/classes for Connect 4 game.
187+
* Minor documentation cleanup.
188+
189+
#### 0.10.3-Chp17n21-Rewrite-DF1 : 16 Sept 2011
190+
* Fixed defect in FrequencyCounter when reset.
191+
192+
#### 0.10.2-Chp17n21-Rewrite : 16 Sept 2011
193+
* All of the algorithms from Chapters 17 and 21 have been rewritten.
194+
* 17.4 Value-Iteration
195+
* 17.7 Policy-Iteration
196+
* 21.2 Passive-ADP-Agent
197+
* 21.4 Passive-TD-Agent
198+
* 21.8 Q-Learning-Agent
199+
* Rewrote Cell World Environment (environment.cellworld) to be independent of use.
200+
* Re-organized probability.hmm package.
201+
* Minor optimization to FrequencyCounter implementation.
202+
* Documentation clean up.
203+
204+
#### 0.10.1-Chp15-Rewrite : 31 Jul 2011
205+
* All of the algorithms from Chapter 15 have been rewritten.
206+
* 15.4 Forward-Backward (3 implementations provided)
207+
* 15.6 Fixed-Lag-Smoothing
208+
* 15.17 Particle-Filtering
209+
* Added an Iterator interface and supporting methods to CategoricalDistribution and Factor.
210+
* ProbabilityTable.Iterator removed getPostIterateValue() method from API due to not being general.
211+
* Fixed Issue 63 - all compilation warnings have been resolved or suppressed where appropriate for now.
212+
* Documentation clean up.
213+
214+
#### 0.10.0-Chp13-and-14-Rewrite : 03 Jul 2011
215+
* All of the algorithms from Chapters 13 and 14 have been rewritten.
216+
* Rewritten:
217+
* 14.9 Enumeration-Ask
218+
* 14.13 Prior-Sample
219+
* 14.14 Rejection-Sampling
220+
* 14.15 Likelihood-Weighting
221+
* 14.16 GIBBS-Ask
222+
* Added:
223+
* 14.11 Elimination-Ask
224+
* Moved Randomizer interface and related implementation underneath
225+
`aima.core.util.`
226+
* Moved TwoKeyHashMashMap to sub-package datastructure.
227+
* Fix for Issue 66
228+
* Documentation clean up.
229+
230+
#### 0.9.14-Probability-and-Logic-Fixes : 20 Mar 2011
231+
* Resolved Issue 58, related to forward-backward algorithm.
232+
* Fixed defect in Unifier that would cause incorrect unifications in particular
233+
edge cases (which would cause unsound proofs).
234+
* Fixed defect in resolution proof step output, that would show an incorrect
235+
unification. In addition, updated proof step information to make easier
236+
to read.
237+
238+
#### 0.9.13-UBUNTU-Fixes : 19 Dec 2010
239+
* Resolved Issue 56, related to compilation and test failures on Ubuntu platform.
240+
* Propositional ask-tell logic fixed using DPLL.
241+
* Map of Australia location corrected.
242+
* Minor code clean up/re-factoring
243+
244+
#### 0.9.12-Online+CSP-Improvements : 05 Nov 2010
245+
* StateAction replaced by TwoKeyHashMap (Online Search)
246+
* NotifyEnvironmentViews renamed to EnvironmentViewNotifier.
247+
* Method createExogenousChange reintroduced (from AIMA2e implementation).
248+
* CSP constraint propagation result handling code cleaned up.
249+
250+
#### 0.9.11-CSP+PathCost-Fixes : 02 Oct 2010
251+
* Fixed defect in Breath First Search where the Path Cost metric was not being updated correctly (issue #54).
252+
* Fixed CSP issue with respect to domain reconstruction with backtracking search.
253+
* Re-introduced SimpleEnvironmentView so its easier for people to setup and play with the code.
254+
* Minor documentation improvements.
255+
256+
#### 0.9.10-CSP+AC-3 : 22 Aug 2010
257+
* CSP package significantly restructured, added AC-3 implementation.
258+
* Search can now create more than one solution within the same run (see `aima.core.search.framework.SolutionChecker`).
259+
* The N-Queens representation now supports incremental as well as complete-state problem formulation.
260+
* Minor clean-ups included.
261+
* Now compiles on Android 2.1.
262+
263+
#### 0.9.9-AIMAX-OSM Minor Fixes : 09 Feb 2010
264+
* Java Doc now uses newer package-info.java mechanism.
265+
266+
#### 0.9.8-AIMAX-OSM Added : 06 Feb 2010
267+
* Minor updates to support addition of aimax-osm project to AIMA3e-Java.
268+
* Vacuum world locations changed from enum to Strings to better support extensibility.
269+
* Queue Searches may now be canceled from within a thread (see CancelableThread).
270+
271+
#### 0.9.7-AIMA3e Published : 10 Dec 2009
272+
First full release based on the 3rd edition of AIMA. The following major
273+
updates have been included in this release:
274+
* Re-organized packages to more closely reflect AIMA3e structure:
275+
* Renamed basic to agent
276+
* Moved general purpose data structures underneath util.
277+
* Moved all Environment implementations under environment.
278+
* Agent package defined now in terms of interfaces as opposed to
279+
abstract classes.
280+
* Added explicit Action interface.
281+
* General improvements/enhancements across all the APIs.
282+
* All algorithms from chapters 1-4 have been updated to reflect
283+
changes in their description in AIMA3e. Primarily this involved
284+
splitting the Successor function concept from AIMA2e into
285+
separate Action and Result functions as described in AIMA3e.
286+
* All tests have been updated to JUnit 4.7, which is included
287+
explicitly as a testing dependency of this project (see /lib).
288+
* Bug fixes to OnlineDFSAgent and GeneticAlgorithm implementations.
289+
* SetOPs, converted to use static methods based on:
290+
http://java.sun.com/docs/books/tutorial/collections/interfaces/set.html
291+
* Queue implementations now extends Java's corresponding collection classes.
292+
* Dependencies between Map Agents and their Environment have been
293+
decoupled by introducing appropriate intermediaries.
294+
* All source formatted using Eclipse 3.4 default settings.
295+
296+
#### 0.95-AIMA2eFinal : 03 Oct 2009
297+
Last full release based on the 2nd edition of AIMA. This is our first release
298+
containing GUIs (thanks to Ruediger Lunde):
299+
* `aima.gui.applications.VacuumAppDemo`
300+
Provides a demo of the different agents described in Chapter 2 and 3
301+
for tackling the Vacuum World.
302+
* `aima.gui.applications.search.map.RoutePlanningAgentAppDemo`
303+
Provides a demo of the different agents/search algorithms described
304+
in Chapters 3 and 4, for tackling route planning tasks within
305+
simplified Map environments.
306+
* `aima.gui.framework.SimpleAgentAppDemo`
307+
Provides a basic example of how to create your own Agent based
308+
demonstrations based on the provided framework.
309+
310+
This will also be our last full release based on the 2nd edition of AIMA.
311+
We are currently in the planning phases to re-organize this project based
312+
on the 3rd edition of AIMA, which should be available soon.

0 commit comments

Comments
 (0)