Maizal
Pronounced like /'māisɔːl/
Promise based modern Javascript framework to use your favourite algorithms on the web and node
Installing
Using npm:
$ npm install maizalIn the browser
<script src="https://unpkg.com/maizal/dist/maizal.min.js"></script>
Usage
Perform a Breadth-first search
const maizal = require('maizal');
maizal.bfs({
initial: {
position: 1,
},
goals: {
position: 4,
},
actions: [
{
name: 'right',
expand: (state) => {
if (state.position + 1 > 5) return undefined;
return { position: state.position + 1 };
},
},
{
name: 'left',
expand: (state) => {
if (state.position - 1 < 0) return undefined;
return { position: state.position - 1 };
},
},
],
hash: 'position',
})
.then(results => console.log(results))
.catch(error => console.log(error));Perform a Dijkstra search
const maizal = require('maizal');
const config = {
initial: {
position: 3,
},
goals: {
position: 4,
},
actions: [
{
name: 'right',
cost: 50,
expand: (state) => {
if (state.position + 1 > 5) return undefined;
return { position: state.position + 1 };
},
},
{
name: 'left',
expand: (state) => {
if (state.position - 1 < 0) return undefined;
return { position: state.position - 1 };
},
},
],
hash: 'position',
}
async function solveCorridor() {
try {
const results = await maizal.dijkstra(config);
console.log(results);
} catch (error) {
console.error(error);
}
}NOTE:
async/awaitis part of ECMAScript 2017 and is not supported in Internet Explorer and older browsers, so use with caution.
Documentation
The config object
Initial state
| Type | Defaults | Optional | Description |
|---|---|---|---|
| Object | false | Initial state of the search |
Examples
const initial = {
position: [4, 5],
};
const initial = {
name: 'myFancyName',
};Goals
| Type | Defaults | Optional | Description |
|---|---|---|---|
| Object | Array | false | Set of goals states |
Examples
const goals = [
{
position: [10, 12],
},
{
position: [4, 2],
}
];
const goals = {
height: 200,
};Actions
| Type | Defaults | Optional | Description |
|---|---|---|---|
| Object | Array | false | Set of actions to take for each new state |
| Key | Type | Defaults | Optional | Description |
|---|---|---|---|---|
| name | String | 'expand' | true | Action name |
| cost | Int | 1 | true | Action cost |
| expand | Function | false | Function that takes a state as argument and returns the data for the following states |
Examples
const actions = [
{
expand: (state) => {
return { position: state.position + 1 };
}
},
{
expand: (state) => {
return Promise.resolve({ position: state.position - 1});
}
},
{
name: 'myFancyAction',
cost: 80,
expand: (state) => {
if(state.height > 90) {
return;
}
return { height: state.height + 10 };
}
},
];NOTE: Remember to return
undefinedor simplyreturnon forbidden actions to avoid generating infinite states
Hash
Used to establish when two newly generated states are essentially the same , for example, in a maze going to the left one cell and the returning to the same represents essentially the same state and we do not want that
| Type | Defaults | Optional | Description |
|---|---|---|---|
| String|Function | false | Field or function to determine the equality of two states |
Examples
const hash = 'position';
const hash = 'height';
const hash = (state) => `${state.x},${state.y}`;Heuristics
Used to give a state a 'sense of approaching to the goal'. It is a function that returns decreasing values as the closer we get to the goal. It depends purely on your search state representation and you must ensure to provide logical and decreasing values the closer the solution is
| Type | Defaults | Optional | Description |
|---|---|---|---|
| Function | true | Function to determine the 'proximity' to a goal |
Examples
const heuristics = ({ x, y }) => {
// Euclidean distance
return Math.sqrt(((x - goal.x) ** 2) + ((y - goal.y) ** 2));
};
const heuristics = ({ x, y }) => {
// Manhattan distance
return Math.abs((x - goal.x) + (y - goal.y));
};
const heuristics = state => 90 - state.position;A better documentation its on the way.
Engines
Available engines
Uninformed
| Engine | API |
|---|---|
| Breadth-first | bfs |
| Dijkstra | dijkstra |
| Random-search | random |
| Depth-first | dfs |
Informed
| Engine | API |
|---|---|
| Best-first search | bestfs |
| A* | astar |
| Weighted-A* | weightedastar |
Promises
Maizal depends on a native ES6 Promise implementation to be supported. If your environment doesn't support ES6 Promises, you can polyfill.
Name
Maizal comes from the spanish word 'maizal' which basically means 'cornfield'. Cross thinking in different languages I got the idea of a maze solving library and the popular cornfield mazes and therefore maizal as a similar word as maze in spanish.
License
Copyright (c) 2018