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 maizal

In 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/await is 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 undefined or simply return on 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

MIT

Copyright (c) 2018