# GAMCS

**Repository Path**: lionker/GAMCS

## Basic Information

- **Project Name**: GAMCS
- **Description**: GAMCS is a software library that implements the Generalized Agent Model (GAM) using computer
- **Primary Language**: Unknown
- **License**: MPL-2.0
- **Default Branch**: master
- **Homepage**: http://gamcs.andy87.com/
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2015-12-08
- **Last Updated**: 2020-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# [GAMCS](http://gamcs.andy87.com)

*Generalized Agent Model* (**GAM**) is a newly developed, generalized (machine) learning algorithm.    
*Generalized Agent Model and Computer Simulation* (**GAMCS**) is a whole description and implementation of GAM using computer.

## Features

GAM is a very powerful and flexible learning algorithm, which is

- unsupervised, completely autonomous 
- model free, ultimately flexible
- online learning, what it has to learn to do, it learns by doing

GAMCS is a complete description and implementation of GAM using the C++ language, which is

- very fast and stable
- very easy to use
- with support of direct edit and query of model's inner information

## Get Started

### Requirements

GAMCS is implemented in full complaince with the _C++11_ standard, which makes it runnable on almost all the platforms. Dependencies of other external libraries are optional and can be configured when building, this will be talked about in detial below.

### Build and Install

Build and install GAMCS are very easy with the help of cmake. First you need to install [cmake] (http://www.cmake.org/). After that, refer to the following installation steps for your specific platform.

For _Unix-like_ platforms, run the following commands in your shell sequentially.

    cd GAMCS_src_dir
    mkdir build
    cd build
    cmake ../
    make
    sudo make install

For _Windows_, make sure you have at least Visual Studio 2010 installed. Then open the "Visual Studio Command Line" located under the menu "Microsoft Visual Studio 201x --> Visual Studio Tools". In the command line, run the following commands sequentially.

    cd GAMCS_src_dir
    mkdir build
    cd build
    cmake ../

After cmake, the corresponding Visual Studio project files should be generated in the build directory. Open the project using Visual Studio, view and compile it as usual.

Note that, the default compiling will only build GAMCS libraries (both dynamic and static), to build the examples accompanied, do `cd examples` and run `make`, or open the project files using Visual Studio under each example if on Windows.

Several options can be configed with cmake before building. 

- INT_BITS = 8|16|32|64(default), specify the bits of integer which represents Input, Output values in gamcs. The bigger the size, the more states it can represents, while the more memory it will consume. Choose the right size according to your specific situation.
- DEBUG = ON|OFF(default), compile gamcs with or without debug information.
- Other build-in options provided by cmake, see the cmake document for detail.

To change an option, run cmake as `cmake ../ -Dname=value`. 

### Usage

With well-designed and clean interfaces, developping your appliction using GAMCS is quite easy. But before that some knowledge of GAM is needed. It's recommended to read the related documents in advance.

Here is a brief guide for the end-user:

The two core concepts in GAMCS are **Agent** and **Avatar**. An Agent is one kind of _Generialized I/O Model_(**GIOM**), which accepts an State (an alias to Input) a time and produces a corresponding Action (an alias to Output) according to the so-called _Maximun Payoff Rule_(**MPP**). To an Agent, the states and actions are all abstract and meaningless integers (whose bits is specified by option INT_BITS), which can be encoded to represent anything, from a location in space to a path in travelling. An Avatar is an Agent embodied in flesh, that is to say, it gives the states and actions of an Agent the "meanings". To a concrete Avatar, for example, if it's a real robot, the states may be the combined values collected from its multiple physical sensors like light sensor, position sensor and the actions may correspond to light a LED or move a step forward/backward/left/right. If the Avatar is a charactor image-recognition program, the states may be the feature distributions generated by some image processing algorithms, and the actions may correspond to speak out the charactors recognizied in the image.

GAMCS contains both Agent and Avatar interfaces, following which the developers can implement their own Agent and Avatar. As mentioned above, the Agent does not deal with any application-related stuff, all states and actions are abstract integers. Therefore, an implemented Agent was already included in GAMCS, it's fast and stable, which can be used directly.

As to Avatar, however, the states and actions are application-related as mentioned above, it's the user's job to implement his own Avatar according to the problem he wants to solve. Fortunately, this is very easy to be done in GAMCS which only involves in implementing 4 virtual functions of the Avatar interface.

As a summary, a typical usage of GAMCS includes: create your own agent (let's call it YourAvatar) inherited from `class Avatar`, implement the 4 virtual functions, which are:

1. `State percieveState();`, use the "sensors" of YourAvatar to percieve the surrounding, get the concept state it's currently in, encode it to an integer and return it to Agent.
2. `void performAction(Action act);`, when an action was produced by Agent, YourAvatar recieves and recognizes the action integer, and do the real action.
3. `OSpace avaliableActions(State st);`, what are the actions YourAvatar can do in each state?
4. `float originalPayoff(State st);`, for each state, a payoff is associated with it, which controls the like and dislike degree of YourAvatar to that state.

Then, create instances of Agent and YourAvatar respectively, connect YourAvatar with Agent, finally step YourAvatar and make it alive.

For sample codes of usage, check the examples directory accompanied with GAMCS.

### How To Contribute

At least in these ways you can help,

- promote GAM/GAMCS and write documents for it
- use GAM/GAMCS to solve various practical problems to explore the true power of GAM/GAMCS
- implement a more efficient Agent in computer
- help varify GAM and prove the unproved assumptions and conclusions.
- port GAM to other medias rather than computer (GAM is an abstract model, computer is not the only/best way to implement it)
- give your other ingenious ideas about GAM/GAMCS

### Contributors

- Andy Huang <andyspider@126.com>: GAM introducer, GAMCS creator & maintainer

### Website

http://gamcs.andy87.com