readme.txt

aiParts is a set of C++ classes that can be used to develop artificial intelligence for multi-decisi

=================================================================
aiParts                    README                        0.9.3


Website:   http://www.aiparts.org

Everything in this file is on the website.

Release and Credit details are in:  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.

Contact: Brian Marshall at [e-mail] or [phone]


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

   About aiParts
   About rrproj
   Status of the Software
   Making the Sample Programs
   Using aiParts
   Support and Services
   The High-Hope AI Technique
   aiParts Source Files
   The aiParts Open Source Project
   Future Development Notes


= = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
        About aiParts

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

Release and Credit details are in the  RELEASE.txt file.

= = = = = = = = = = = = = = = =
    Using the High-Hope Classes

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

The <a href="highhope.htm">High-Hope technique</a> is a type
of machine-learning.  Options have models of emotions.  The
software learns about the solution space by repeatedly trying
to find a good solution. Emotions affect tries which affect
emotions. Emotions control the balance between exploring the
unknown and taking advantage of what has been learned.

The technique is an application of aiPatterns - see:
  http://www.agt.net/public/bmarshal/aipatterns

= = = = = = = = = = = = = = = =
    Applications for aiParts

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

Two of the sample programs use the High-Hope classes. They
can be used to solve a variety of problems, or as a starting
point in custom development.

  A-to-B - find the shortest path using only distance 
           information, not spatial information

  rrproj - assign people and/or equipment to projects or events

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 decision-tree too large too search

The aipPandemonium class is used as a container-class for:
  - sets, lists
  - structure in one-to-many relationships


= = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
        About rrproj

rrproj is free Open Source software that assigns people 
and/or equipment to projects.

rrproj is a sample program in the aiParts distribution.
It uses the Requirement-Resource and High-Hope classes.

Sample scripts are provided for building and testing the 
solver program. These scripts must be run from the 
directory in which they reside.

A free Open Source graphical user-interface and 
database are being developed using Open Office 3. 

Your organization can develop an applications to use the 
solver, or the solver can be integrated into other software. 

The make script compiles and links a program that reads 
and writes disk files.  A better call interface is planned.


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

aiParts is available for beta testing. The AI is still 
experimental.  

The rrproj sample program needs much more testing.

The rrproj solver is slow. This will be improved.

Any C++ compiler should be able to compile this software.

In September 2008, aiParts 0.9.0 added many new features, 
and the existing code was changed in many places. 
See RELEASES.txt for details.

Most of the code has not changed since version 0.8.5 and
it has had a fair bit of testing with the sample programs.

The rrproj sample program has had a little testing, which
also tested the changes in the aiParts code.

There is much to be done to improve aiParts - see the 
last section of this file. 


= = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
        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

For the rrproj sample program, see these files in the
rrproj subdirectory:
   mk_windows_rrproj.bat
   mk_linux_rrproj.sh

On Windows, the script is written to use the
Borland 5.5 C++ compiler and library.  They are free,
high-quality and they are run from the command line.

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.


= = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
        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.


= = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
        Support and Services

Suggestions for enhancements and changes are always welcome.

FAQ pages will be on the website in the future.

aiParts software is Open Source - you get the source code.  
Anyone you want can support it, add to it, change it or 
use it in other software.

Services are available by independent firms and developers.
These services are not endorsed by the aiParts project. 

Setup, support, analysis and development services are
available by Brian Marshall, the developer of aiParts
and rrproj.  Contact:
    [e-mail]
    [phone]  (and leave a message if necessary)


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

The High-Hope technique is used to find solutions to 
problems in which a number of decisions have to be made 
and each decision affects subsequent decisions.

The technique can be useful for many types of problems, 
including arbitrarily constrained problems that have an 
enormous number of possible solutions.

The technique is easy to implement in software, and easy 
to specialize to solve a particular type of problem. 
Software size and complexity grow very slowly with an 
increase in the number of problem constraints. 

For more information, see www.aiparts.org/highhope.htm

= = = = = = = = = = = = = = = =
    The Technique

The High-Hope Technique...

 - Given a problem, try to solve it repeatedly (physically 
   or by consideration) and remember the best solution(s).
  
 - In a try, where there is a choice of which decision 
   to address next, choose the one that is most urgent - 
   either because it is particularly important or it is 
   particularly safe.

 - At each decision, pick the option with the most hope
   for success. The hope of an option is the sum of