=================================================================
aiParts                    README                        0.9.1


Project Home Page:   http://www.aiparts.org

To see what is new in this release, see the file: RELEASE.txt

This is Open Source software.  Download it free of charge.
Do whatever you want with it.  There is NO warranty; not even 
for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  
See the file LICENSE.txt.

As an Open Source project, contributions are always welcome:
software, documentation, bug reports, enhancement requests,
comments and criticism.

Contact: Brian Marshall at bmarshal@agt.net or +1-403-651-0584


= = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
        Table of Contents

   Introduction to aiParts
   Status of the Software
   Status of the AI
   Making the Sample Programs
   Using aiParts
   The High-Hope AI Technique
   aiParts Source Files
   Future Development Notes


= = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
        Introduction to aiParts

aiParts is a set of C++ classes that can be used to develop 
artificial intelligence in multi-decision problems. It includes 
classes that implement the High-Hope technique and some small 
sample programs.

An application can assemble a problem from subclasses of the 
High-Hope classes. The problem class has a solve() function 
that will search for a good solution.

The High-Hope technique is an example of machine-learning. 
Options have models of emotions which affect and are affected 
by repeated attempts to solve the problem. The chaotic 
interaction between emotions controls the balance between
exploring the unknown and taking advantage of what has been 
learned.

aiParts can be used:
  - in applications, to make decisions or solve problems
  - as a platform for AI research and development

Examples of multi-decision problems: 
  - navigating through streets, pipelines or networks
  - assigning packages to couriers
  - assigning people and equipment to projects
  - staff scheduling
  - scheduling steam-injection in a heavy-oil field
  - exploring a solution-space too large too search

A "find the shortest path from A to B" sample program uses
the High-Hope classes.

Subclasses of the High-Hope classes can be developed for 
a problem-domain.  aiParts includes rr_solve.h/cpp for 
Requirement-Resource problems - packages and couriers,
projects and staff/equipment, etc.


= = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
        Status of the Software

Any C++ compiler should be able to compile this software.
It is basic C++.  The aipPandemonium class is used as a
general container-class.

aiParts 0.9.1 provides improvements in this README.txt file.

aiParts 0.9.0 has many new features - see the RELEASES.txt
file.  These features were added during the development of 
staff-assignment software in the StaffWhen and rrSolve
Open Source projects.

The new aiParts software has had some alpha-testing.  The
older aiParts software has had a fair bit of alpha-testing,
both with the sample programs and during the debugging and
testing of the StaffWhen solver software.

aiParts is ready for beta-testing.


= = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
        Status of the AI

The High-Hope AI technique appears to be work moderately 
well.  There is much that can be done to improve it - see 
the last section of this file.

The AI is ready for initial beta testing.

The High-Hope technique is chaotically sensitive to initial 
conditions, parameters and the sequence of random numbers 
it uses for choosing equal options.  A tiny change in the 
software or the problem can result in a different choice in 
a try, which may affect subsequent choices and tries.

The High-Hope technique and rr_solve.h/cpp are used in 
solver software used by two Open Source projects:
  rrSolve  -  assign people and/or equipment to projects
  StaffWhen - assign staff to events
The source for this solver will probably be released in
late-September 2008. The project websites URLs will change. 
Search Google for:  rrSolve  and/or  StaffWhen


= = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
        Making the Sample Programs

Sample scripts are provided for building the sample 
programs on Windows and Linux machines.  They will
generally have to be modified for the particular
compiler (and possibly library) that you use.

See the files:
   mk_samples_windows.bat
   mk_samples_linux.sh
   mk_samples_linux2.sh

On Unix/Linux systems, you might want to change g++ 
(which is good for Fedora) to gcc or cc or CC or
whatever command you use to run your compiler.

If you want a free compiler for Windows, and you like to
work from the command line, you might want to try the
Borland 5.5 C++ compiler.


= = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
        Using aiParts

There are two approaches to using aiParts...

The first approach is to:
 - Identify the most abstract layer of aiParts that is 
     appropriate for your problem and develop a set of
     subclasses that specialize them for your problem.
 - Write a program that assembles a problem from your
     new classes and call the appropriate virtual
     function(s) - like: yourDecision.decide() or
     yourProblem.solve().

The second approach is to:
 - Identify the sample program (or other software using
     aiParts) that is closest to your problem, and take
     a copy of the source files.
 - Identify the classes that specialize the aiParts
     software for the particular problem and incrementally
     modify them to address your problem.

The second approach is easier because you learn how 
the aiParts software works as you go, rather than having
to learn about it right from the start.


= = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
        The High-Hope AI Technique

At the highest level, the High-Hope technique tries to
solve the problem many times, remembering the best try
found. At each decision, the option with the highest
'hope for success' is chosen.

The success or failure of each try affects strategic aspects
in relevant options. These aspects affect the hope of the 
options.  Tries affect aspects which affects tries - it is
a chaotic system.  It causes one try to (usually) differ
from the next).

The High-Hope AI technique uses simplistic models of some 
emotions.  The emotions have names that are misleading
because the words have multiple subtle meanings. This is
probably unavoidable.  

The hope of an option is the feeling that the option is a 
good choice - that it could be part of the best solution 
that will be found.

In aiParts, Hope is a composite emotion:
   Fear      -  the desire to avoid something bad
   Greed     -  the desire for something known and good
   Curiosity -  the desire to try something new
   Hope      -  Fear + Greed + Curiosity

Why emotions?  Consider deer and fear.  It is easy to
define a bunch of different reasons why a deer might become
more or less afraid; when the fear is high enough, the deer
runs away.  It is much more difficult to design an algorithm 
to decide when a deer should run away.

As a chaotic system, the High-Hope technique is extremely 
sensitive to the initial state.  It might find a good 
solution to a problem in 50 or 500 or 5000 tries.  Trying 
is how it learns about the problem.  When solving a problem,
it is worth experimenting with the number of tries.

Changing the number of tries will change various cutoff
values (ex. max tries without an improvement), and this
will change the series of solutions that are found.

In the A-to-B sample program, if the last parameter is
a 2, you can see the fear, greed and curiosity changing as 
the software considers each option in each try:
    samp_4_a_to_b.exe  A  B  30  2  >samp_A_B.txt
This can produce a lot of output, so it was redirected to 
a file.


= = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
        aiParts Source Files

Files generally depend on the files above it in this list...

  Low-Level Types, Base Class and Utility Classes:
    aipTime.h          Time and date
    aipGood.h          Goodness
    aipBase.h          base class, messages, random numbers

  Classes that implement AI Patterns:
    aipPandemonium.h   Pandemonium, demons
    aipEmotion.h       Emotion - Fear, Greed, Curiosity, Hope

  Classes for Decision-Making and Problem-Solving:
    aipDecision.h      Decisions, options
    aipProblem.h       Problems

  Classes that implement AI techniques:
    aipHighHope.h      High-Hope problem-solving

  Classes that specialize AI techniques:
    rr_solve.h         Requirement-Resource frame-work

                  Files for Sample Programs

samp_time.cpp          Using the date and time classes
samp_good.cpp          Using the goodness class
samp_pandemonium.cpp   Using the container class
samp_decision.cpp      Making decisions using an emotion
   samp_deer_fear.h
   samp_deer_fear.cpp
samp_a_to_b.cpp        Navigating using the High-Hope classes
   samp_a2b.h
   samp_a2b.cpp


= = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
Future Development Notes

Developing new AI techniques (alternatives to the High-Hope
technique)

Developing abstraction-layers for an AI technique (just as
the classes in rr_solve.h/cpp specialize the High-Hope
technique for Requirement-Resource problems)

aipTime.h/cpp: add seconds to class aipTimeOfDay

There is much that can be done to improve the High-Hope AI: 
 - improve the choice of which decision to decide next
 - improve the behavior in the exploring stage
 - maybe add an initial feeling-out stage
 - improve the refining stage
 - analyze the output for sequences and cycles
 - improve how the AI gets out of ruts
 - further improvement of the way hope works
 - and many other ways of refining the AI

   Handling Failure
Maybe: If a try fails, decisions and options later in the 
solution get more fear than those earlier in the solution.

   Good But Different
Recognize when a good result is significantly different from
other good results found.

   Handling Good Improvements
After a recent try that was a good-improvement, increase 
the curiosity of acceptable-looking options that look like 
they would have a significant effect on the solution.  A 
"good-improvement" is a try that is better than the current 
best-so-far try or acceptably good and significantly different
than the best-so-far try.

   Problem-Hope
The problem itself could have a hope which affects how option
hopes are determined.  The idea is that if problem-curiosity is 
high, the aspects that control curiosity in options would be 
given more weight.  The same principle would apply to fear and 
greed.  This would allow for higher curiosity (and more 
exploration) early in the problem-solving, and lower curiosity 
(and more optimization) later in the problem-solving.

   Finding Best Path When on New Path
If following a new path and come to the best-so-far path, 
keep following the bsf path.  This could be done with 
problem-hope; when a node in the bsf solution is chosen, 
drop problem-curiosity to (near) aipNeurtal.

   Implement Ways
A 'way' is a set of options chosen for a set of decisions.
Maybe, in a try, force some ways while exploring other ways.

=================================================================

