Skip to content
Permalink
Browse files

Add github io pages docs. (#175)

* Added initialization for github-pages

* Create index.md

* Set theme jekyll-theme-minimal

* created sub-page for jaicore-basic

* Added mlplan-documentation

* adjusted documentation

* added s sub-title

* Changed project layout

* Changed header type for section headers to ##

* resolved syntax errors

* Created configuration for ML-Plan

* added documentation overview, reformatted navigation

* Updated jaicore-search documentation

* Added jaicore-search documentation

* adjusted link to get back to main page

* Updated contents outline on main page

* Updated AILibs documentation
  • Loading branch information...
mwever authored and fmohr committed Jul 8, 2019
1 parent 610ddc5 commit c1c6be577ffeed00da11f7a68a9f4cfdc9d72d80
@@ -254,3 +254,7 @@ gradle-app.setting
JAICore/jaicore-ml/tmp/
JAICore/jaicore-ml/model_dumps/
JAICore/jaicore-ml/testsrc/ml/scikitwrapper/importfolder_test/__pycache__/
/docs/Gemfile
/docs/Gemfile.lock
/docs/_site
/docs/.sass-cache
@@ -0,0 +1,2 @@
theme: jekyll-theme-minimal
logo: img/ailibs-logo.png
@@ -0,0 +1,28 @@
<!DOCTYPE html>
<html lang="{{ site.lang | default: "en-US" }}">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">

{% seo %}
<link rel="stylesheet" href="{{ "/assets/css/style.css?v=" | append: site.github.build_revision | relative_url }}">
<!--[if lt IE 9]>
<script src="https://cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv.min.js"></script>
<![endif]-->
</head>
<body>
<div class="wrapper" style="width: 1300px;">

{{ content }}

<footer>
{% if site.github.is_project_page %}
<p>This project is maintained by <a href="{{ site.github.owner_url }}">{{ site.github.owner_name }}</a></p>
{% endif %}
<p><small>Hosted on GitHub Pages &mdash; Theme by <a href="https://github.com/orderedlist">orderedlist</a></small></p>
</footer>
</div>
<script src="{{ "/assets/js/scale.fix.js" | relative_url }}"></script>
</body>
</html>
@@ -0,0 +1,47 @@
---
layout: default
---
<div style="width: 300px; float: left; position: fixed;">
{% if site.logo %}
<a href="{{ "/" | absolute_url }}"><img src="{{site.logo | relative_url}}" alt="Logo" /></a>
{% endif %}

<h2>AILibs Projects</h2>
<ul style="margin: -10px;">
<li>
<h3>JAICore</h3>
<ul style="margin-top: -10px;">
<li><h3 style="margin: 8px 0px;">jaicore-algorithminspector</h3></li>
<li><h3 style="margin: 8px 0px;">jaicore-basic</h3></li>
<li><h3 style="margin: 8px 0px;">jaicore-ea</h3></li>
<li><h3 style="margin: 8px 0px;">jaicore-experiments</h3></li>
<li><h3 style="margin: 8px 0px;">jaicore-logic</h3></li>
<li><h3 style="margin: 8px 0px;">jaicore-math</h3></li>
<li><h3 style="margin: 8px 0px;">jaicore-ml</h3></li>
<li><h3 style="margin: 8px 0px;">jaicore-planning</h3></li>
<li><h3 style="margin: 8px 0px;"><a href="projects/jaicore-search">jaicore-search</a></h3></li>
</ul>
</li>
<li><h3>HASCO</h3></li>
<li><h3><a href="projects/mlplan">ML-Plan</a></h3></li>


{% if site.github.is_project_page %}
<p class="view"><a href="{{ site.github.repository_url }}">View the Project on GitHub <small>{{ site.github.repository_nwo }}</small></a></p>
{% endif %}

{% if site.github.is_user_page %}
<p class="view"><a href="{{ site.github.owner_url }}">View My GitHub Profile</a></p>
{% endif %}

{% if site.show_downloads %}
<ul class="downloads">
<li><a href="{{ site.github.zip_url }}">Download <strong>ZIP File</strong></a></li>
<li><a href="{{ site.github.tar_url }}">Download <strong>TAR Ball</strong></a></li>
<li><a href="{{ site.github.repository_url }}">View On <strong>GitHub</strong></a></li>
</ul>
{% endif %}
</div>
<section style="width: 1000px;">
{{ content }}
</section>
@@ -0,0 +1,40 @@
---
layout: default
---
<header style="width: 300px;">
{% if page.logo %}
<a href="{{ "/" | absolute_url }}"><img src="./img/{{ page.logo }}" alt="{{ page.title}}" style="width: 270px;" /></a>
{% else %}
<a href="{{ "/" | absolute_url }}"><img src="{{site.logo | relative_url}}" alt="Logo" style="width: 270px;" /></a>
{% endif %}
<p>{{ page.title }} is an <a href="{{ "/" | absolute_url }}">AILibs</a> library</p>
<h1>{{ page.title }}</h1>


{% if page.navigation %}

{% for item in page.navigation %}
<h3 {% if page.navigation_active == item.id %}class="active"{% endif %}>
{% if page.navigation_mode == 'anchor' %}
<a href="#{{ item.link }}" > {{ item.title }}</a>
{% else %}
<a href="{{ item.link }}#content" > {{ item.title }}</a>
{% endif %}
</h3>
{% endfor %}
{% endif %}

</header>
<section style="width: 1000px;">{{ content }}

<!-- All projects should have Contributions being their last entry -->
<p>
We welcome contributions to {{ page.title }} given that the code quality meets our standards.
If you would like to add changes to {{ page.title }}, feel free to create a pull request on the `dev` branch.
</p>
<p>Please consider the following:</p>
<ul>
<li>provide a comprehensive description of your changes and why they are helpful</li>
<li>we cannot leave any copyright to third party authors. Creating the pull request, you accept to transfer the copyright to AILibs for being published under its current license (AGPL for now)</li>
</ul>
</section>
@@ -0,0 +1 @@
Test
Binary file not shown.
@@ -0,0 +1,18 @@
---
layout: main
---
[![Build Status](https://travis-ci.com/fmohr/AILibs.svg?branch=dev)](https://travis-ci.com/fmohr/AILibs)
[![Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=starlibs.ailibs&metric=alert_status)](https://sonarcloud.io/dashboard/index/starlibs.ailibs)
[![SonarCloud Coverage](https://sonarcloud.io/api/project_badges/measure?project=starlibs.ailibs&metric=coverage)](https://sonarcloud.io/component_measures?id=starlibs.ailibs&metric=coverage&view=list)
[![Maven Central](https://maven-badges.herokuapp.com/maven-central/ai.libs/jaicore-basic/badge.svg)](https://search.maven.org/#search%7Cgav%7C1%7Cg%3A"ai.libs)
[![Javadocs](https://javadoc.io/badge/ai.libs/jaicore-basic.svg)](https://javadoc.io/doc/ai.libs/jaicore-basic)


# AILibs
AILibs is a collection of Java libraries related to automated decision making. It currently consists of two building blocks. It is also home of the current version of the AutoML-tool [ML-Plan](https://github.com/fmohr/AILibs/tree/master/softwareconfiguration/mlplan).

* **JAICore** (Java AI Core) is a collection of projects with basic general purpose AI algorithms mainly in the area of logic reasoning, heuristic search, and machine learning
* **softwareconfiguration** is a collection of projects related to automatically configuring software systems. Here we also maintain the code for our AutoML flagship **[ML-Plan](https://fmohr.github.io/AILibs/projects/mlplan)**



@@ -0,0 +1,12 @@
[![Build Status](https://travis-ci.com/fmohr/AILibs.svg?branch=dev)](https://travis-ci.com/fmohr/AILibs)
[![Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=starlibs.ailibs&metric=alert_status)](https://sonarcloud.io/dashboard/index/starlibs.ailibs)
[![SonarCloud Coverage](https://sonarcloud.io/api/project_badges/measure?project=starlibs.ailibs&metric=coverage)](https://sonarcloud.io/component_measures?id=starlibs.ailibs&metric=coverage&view=list)
[![Maven Central](https://maven-badges.herokuapp.com/maven-central/ai.libs/jaicore-basic/badge.svg)](https://search.maven.org/#search%7Cgav%7C1%7Cg%3A"ai.libs)
[![Javadocs](https://javadoc.io/badge/ai.libs/jaicore-basic.svg)](https://javadoc.io/doc/ai.libs/jaicore-basic)


# AILibs
AILibs is a collection of Java libraries related to automated decision making. It currently consists of two building blocks. It is also home of the current version of the AutoML-tool [ML-Plan](https://github.com/fmohr/AILibs/tree/master/softwareconfiguration/mlplan).

* **JAICore** (Java AI Core) is a collection of projects with basic general purpose AI algorithms mainly in the area of logic reasoning, heuristic search, and machine learning
* **softwareconfiguration** is a collection of projects related to automatically configuring software systems. Here we also maintain the code for our AutoML flagship **[ML-Plan](https://github.com/fmohr/AILibs/tree/master/softwareconfiguration/mlplan)**
@@ -0,0 +1,162 @@
---
layout: project
title: jaicore-search
version: 0.1.5
navigation_mode: anchor
navigation:
- { id: "overview", link: "overview", title: "Overview" }
- { id: "installation", link: "installation", title: "Installation" }
- { id: "usage", link: "usage", title: "Usage" }
- { id: "javadoc", link: "javadoc", title: "JavaDoc" }
- { id: "contribute", link: "contribute", title: "Contribute" }
navigation_active: overview
---

# jaicore-search
**jaicore-search** is a library for heuristic search.

## Overview
With the algorithms contained in jaicore-search, you can search tree-structured graphs with
* Depth First Search
* Best First Search (including A* and variants such as AWA*)
* MCTS
* Limited Discrepancy Search
* Random Search
* R*

## Installation
You can bind in jaicore-search via a Maven dependency (using Maven central as repository).
### Maven
```
<dependency>
<groupId>ai.libs</groupId>
<artifactId>{{ page.title }}</artifactId>
<version>{{ page.version }}</version>
</dependency>
```

### Gradle
```gradle
dependencies {
implementation 'ai.libs:{{ page.title }}:{{ page.version }}'
}
```

## Usage
### At a Glance
For every search algorithm, jaicore-search provides a distinct class that implements the `IAlgorithmInterface` and, hence, can be used in a step-wise manner.
In particular, this means that you can iterate over the search algorithm object, and each iteration gives you an of the search algorithm.
In the simplest case, the algorithm steps once for every solution path, but, depending on the concrete search algorithm, there may also be steps for much more subtle events such as a node added to the model or a type switch of a node.

To apply a search algorithm to a graph, three steps are necessary:
1. create an object representing the search problem
2. create a new search algorithm instance for the problem
3. run the search algorithm

A minimal code example in jaicore-search for the 8-queens problems looks like this:
```java
GraphSearchInput<QueenNode, String> input = new GraphSearchInput<>(new NQueensGraphGenerator(8));
RandomSearch<QueenNode, String> rs = new RandomSearch<>(input);
SearchGraphPath<QueenNode, String> solution = rs.call();
System.out.println(solution);
```
Note that search problems and algorithms are always generic in (at least) the labels associated with nodes (here `QueenNode`) and labels associated with edges (here `String`).

In the following, these steps are described in some more detail, and we describe alternative problem formulations and algorithms.

### In-Depth
#### Defining a Search Problem
Every search algorithm receives an object of the type `GraphSearchInput` (or one of its sub-types) as input.
Such an input provides a `GraphGenerator` and, depending on the concrete sub-class, potentially other objects such as path evaluators, heuristics, etc.
jaicore-search already comes with a number of `GraphGenerator` classes for standard AI search problems, which you can have a look at to understand how these work.

For example, to create a search problem for the 8-queens problem, you can do the following:
```java
GraphSearchInput<QueenNode, String> input1 = new GraphSearchInput<>(new NQueensGraphGenerator(8));
```

Some algorithms can already work with this kind of problem, e.g. `RandomSearch`.
Some algorithms, however, need additional input.
For example, BestFirstSearch requires a function that can evaluate arbitrary paths starting from the root (typically called *f*).
To this end, a more specific input object can be created:
```java
GraphSearchWithSubpathEvaluationsInput<QueenNode, String, Double> input2 = new GraphSearchWithSubpathEvaluationsInput<>(new NQueensGraphGenerator(4), p -> 0.0);
```
Here, the evaluator simply assigns a constant 0.0 to each path.
You may also observe that this input problem has an additional generic parameter (`Double`), which is the class for the node evaluations.
Often, these are `Double`, but you can also you more complex evaluations like vectors etc. as long as they implement the `Comparable` interface.

#### Initializing and Configuring the Search Algorithm
Every search algorithm can be instantiated with a problem instance that corresponds to its input type.
```java
RandomSearch<QueenNode, String> rs = new RandomSearch<>(input1);
StandardBestFirst<QueenNode, String> bf = new StandardBestFirst<>(input2);
```
Since every search algorithm implements the `IAlgorithm` interface, a timeout, and conditions on CPU usage, and maximum threads can be defined.
```java
rs.setTimeout(new TimeOut(10, TimeUnit.SECONDS));
rs.setNumCPUs(4);
rs.setMaxNumThreads(8);
```

#### Running a Search Algorithm
You can simply invoke the `call` method to obtain any solution.
```java
SearchGraphPath<QueenNode, String> solution = rs.call();
```

For algorithms that evaluate paths, you get a more specific object, an `EvaluatedSearchGraphPath`, which you can ask for the score of the solution:
```java
EvaluatedSearchGraphPath<QueenNode, String, Double> solution = bf.call();
Double score = solution.getScore();
```

Alternatively, you can iterate over *all solutions* using
```java
while (true) {
SearchGraphPath<QueenNode, String> solution = rs.nextSolutionCandidate();
}
```
Note that this throws a `NoSuchElementException` if no more solutions exist.

For iterating over *all events*, use:
```java
for (AlgorithmEvent e : bf) {
if (e instanceof EvaluatedSearchSolutionCandidateFoundEvent) {
EvaluatedSearchGraphPath<QueenNode, String, Double> solution = ((EvaluatedSearchSolutionCandidateFoundEvent<QueenNode, String, Double>)e).getSolutionCandidate();
double score = solution.getScore();
System.out.println(score);
}
}
```
In this example, we only consider events that indicate the encounter of a solution, but there are many more events that you can react to.
A list of supported events per algorithm is given in the documentation of the respective algorithm.

You may note that the library adopts Java Generics in a very exhaustive way, and that class names appear sometimes quite complicated (long).
In AILibs, we are trading off readibility, reliability, reusability, and API comfort.
The strongly generic architecture gives AILibs an enormous potential of reusability of code.
API comfort in itself is a goal that needs to trade-off between short syntax and semantic safety.
With less generics, the code that uses our API would be shorter and perhaps a bit easier to read, but generics have the advantage of giving type guarantees at compile time, and relief you from the need of casting.
Our general approach is to try to hide as much of the generics as possible in internal structures, such that API users benefit from generics as much as possible while suffering as little as possible from the overhead that comes along with it.

### List of Search Algorithms

| Algorithm | Input | Output |
| ------------- |-------------|-----|-----|
| DepthFirstSearch | GraphSearchInput | SearchGraphPath |
| RandomSearch | GraphSearchInput | SearchGraphPath |
| MCTSPathSearch | GraphSearchWithPathEvaluationsInput | EvaluatedSearchGraphPath |
| UCTPathSearch | GraphSearchWithPathEvaluationsInput | EvaluatedSearchGraphPath |
| StandardBestFirst | GraphSearchWithSubpathEvaluationsInput | EvaluatedSearchGraphPath |
| AStar | GraphSearchWithNumberBasedAdditivePathEvaluation | EvaluatedSearchGraphPath |
| RStar | GraphSearchWithNumberBasedAdditivePathEvaluationAndSubPathHeuristic | EvaluatedSearchGraphPath |
| AwaStarSearch | GraphSearchWithSubpathEvaluationsInput | EvaluatedSearchGraphPath |
| BestFirstLimitedDiscrepancySearch | GraphSearchWithNodeRecommenderInput | EvaluatedSearchGraphPath |


## JavaDoc
JavaDoc is available [here](https://javadoc.io/doc/ai.libs/jaicore-search/).

## Contribute
jaicore-search is currently developed in the [JAICore/jaicore-search folder of AILibs on github.com](https://github.com/fmohr/AILibs/tree/master/JAICore/jaicore-search).

Binary file not shown.

0 comments on commit c1c6be5

Please sign in to comment.
You can’t perform that action at this time.