const activation = require('./activation');
/**
*
* Genetic algorithm mutation methods. Creates variations (mutations) in neural networks which are then selected for better performance.
*
* @namespace mutation
*
* @see {@link https://en.wikipedia.org/wiki/mutation_(genetic_algorithm)|Mutation (genetic algorithms) on Wikipedia}
* @see {@link https://en.wikipedia.org/wiki/Genetic_algorithm#Selection|Selection (genetic algorithms) on Wikipedia}
*
* @example <caption>Mutation methods with networks</caption>
* let { methods, Network } = require("@liquid-carrot/carrot");
*
* let myNetwork = new Network(5, 10, 5);
*
* // Setting a mutation method for a network
* myNetwork.mutate(methods.mutation.ADD_NODE);
*
* // specifying a list of network mutation methods to use during evolution
* myNetwork.evolve(trainingset, {
* mutation: [methods.mutation.MOD_BIAS, methods.mutation.ADD_NODE]
* }
*
* @example <caption>Using a mutation method with a neuron</caption>
* let { methods, Network } = require("@liquid-carrot/carrot");
*
* let myNetwork = new Network(5, 10, 5);
*
* myNode.mutate(methods.mutation.MOD_BIAS);
*/
const mutation = {
/**
* @constant
* @type {object}
* @description Adds a node
* @default
*
* @prop {boolean} randomActivation=true If enabled, sets a random activation function on the newly created node
*
* @example
* let { methods, Network } = require("@liquid-carrot/carrot");
*
* let myNetwork = new Network(5, 10, 5);
*
* myNetwork.mutate(methods.mutation.ADD_NODE);
*/
ADD_NODE: {
name: 'ADD_NODE',
randomActivation: true,
},
/**
* @constant
* @type {object}
* @description Removes a node
* @default
*
* @prop {boolean} keep_gates=true Ensures replacement node has gated connections if the removed node did.
*
* @example
* let { methods, Network } = require("@liquid-carrot/carrot");
*
* let myNetwork = new Network(5, 10, 5);
*
* myNetwork.mutate(methods.mutation.SUB_NODE);
*/
SUB_NODE: {
name: 'SUB_NODE',
keep_gates: true,
},
/**
* @constant
* @type {object}
* @description Adds a connection between two nodes
* @default
*
* @example
* let { methods, Network } = require("@liquid-carrot/carrot");
*
* let myNetwork = new Network(5, 10, 5);
*
* myNetwork.mutate(methods.mutation.ADD_CONN);
*/
ADD_CONN: {
name: 'ADD_CONN',
},
/**
* @constant
* @type {object}
* @description Removes a connection between two nodes
* @default
*
* @example
* let { methods, Network } = require("@liquid-carrot/carrot");
*
* let myNetwork = new Network(5, 10, 5);
*
* myNetwork.mutate(methods.mutation.SUB_CONN);
*/
SUB_CONN: {
name: 'REMOVE_CONN',
},
/**
* @constant
* @type {object}
* @description Modifies the weight of a connection
* @default
*
* @prop {number} min=-1 lower bound for weight modification
* @prop {number} max=1 higher bound for weight modification
*
* @example
* let { methods, Network } = require("@liquid-carrot/carrot");
*
* let myNetwork = new Network(5, 10, 5);
*
* myNetwork.mutate(methods.mutation.MOD_WEIGHT);
*/
MOD_WEIGHT: {
name: 'MOD_WEIGHT',
min: -1,
max: 1,
},
/**
* @constant
* @type {object}
* @description Modifies the bias of a node
* @default
*
* @prop {number} min=-1 lower bound for modification of a neuron's bias
* @prop {number} max=1 higher bound for modification of a neuron's bias
*
* @example
* let { methods, Network } = require("@liquid-carrot/carrot");
*
* let myNetwork = new Network(5, 10, 5);
*
* let myNode = new Node();
*
* myNode.mutate(methods.mutation.MOD_BIAS);
*/
MOD_BIAS: {
name: 'MOD_BIAS',
min: -1,
max: 1,
},
/**
* @constant
* @type {object}
* @description Modifies the activation function of a node by randomly picking from the allowed activation methods
* @default
*
* @prop {boolean} mutateOutput=false Change activation function of network output neurons. Enable this to let the network experiment with its output.
* @prop {activation[]} [allowed=[all built-in activation methods]] Mutation methods to randomly select from when mutating
*
* @example <caption>Mutating the activation function of a node</caption>
* let { methods, Network } = require("@liquid-carrot/carrot");
*
* let myNetwork = new Network(5, 10, 5);
*
* let myNode = new Node();
*
* myNode.mutate(methods.mutation.MOD_ACTIVATION);
*
* @example <caption>Mutating the activation function of a network's nodes</caption>
* let { methods, Network } = require("@liquid-carrot/carrot");
*
* let myNetwork = new Network(5, 10, 5);
*
* let myNode = new Node();
*
* myNode.mutate(methods.mutation.MOD_ACTIVATION);
*/
MOD_ACTIVATION: {
name: 'MOD_ACTIVATION',
mutateOutput: false,
allowed: [
activation.LOGISTIC,
activation.TANH,
activation.RELU,
activation.IDENTITY,
activation.STEP,
activation.SOFTSIGN,
activation.SINUSOID,
activation.GAUSSIAN,
activation.BENT_IDENTITY,
activation.BIPOLAR,
activation.BIPOLAR_SIGMOID,
activation.HARD_TANH,
activation.ABSOLUTE,
activation.INVERSE,
activation.SELU,
],
},
/**
* @constant
* @type {object}
* @description Adds a self-connection to a node
* @default
*
* @example
* let { methods, Network } = require("@liquid-carrot/carrot");
*
* let myNetwork = new Network(5, 10, 5);
*
* myNetwork.mutate(methods.mutation.ADD_SELF_CONN);
*/
ADD_SELF_CONN: {
name: 'ADD_SELF_CONN',
},
/**
* @constant
* @type {object}
* @description Removes a self-connection from a node
* @default
*
* @example
* let { methods, Network } = require("@liquid-carrot/carrot");
*
* let myNetwork = new Network(5, 10, 5);
*
* myNetwork.mutate(methods.mutation.SUB_SELF_CONN);
*/
SUB_SELF_CONN: {
name: 'SUB_SELF_CONN',
},
/**
* @constant
* @type {object}
* @description Makes a node gate a connection
* @default
*
* @example
* let { methods, Network } = require("@liquid-carrot/carrot");
*
* let myNetwork = new Network(5, 10, 5);
*
* myNetwork.mutate(methods.mutation.ADD_GATE);
*/
ADD_GATE: {
name: 'ADD_GATE',
},
/**
* @constant
* @type {object}
* @description Removes a gate from a connection
* @default
*
* @example
* let { methods, Network } = require("@liquid-carrot/carrot");
*
* let myNetwork = new Network(5, 10, 5);
*
* myNetwork.mutate(methods.mutation.SUB_GATE);
*/
SUB_GATE: {
name: 'SUB_GATE',
},
/**
* @constant
* @type {object}
* @description Adds a recurrent connection
* @default
*
* @example
* let { methods, Network } = require("@liquid-carrot/carrot");
*
* let myNetwork = new Network(5, 10, 5);
*
* myNetwork.mutate(methods.mutation.ADD_BACK_CONN);
*/
ADD_BACK_CONN: {
name: 'ADD_BACK_CONN',
},
/**
* @constant
* @type {object}
* @description Removes a recurrent connection
* @default
*
* @example
* let { methods, Network } = require("@liquid-carrot/carrot");
*
* let myNetwork = new Network(5, 10, 5);
*
* myNetwork.mutate(methods.mutation.SUB_BACK_CONN);
*/
SUB_BACK_CONN: {
name: 'SUB_BACK_CONN',
},
/**
* @constant
* @type {object}
* @description Swaps the bias and squash function between two nodes
* @default
*
* @prop {boolean} mutateOutput=false Swap bias and activation function of network output neurons too. Disable this to keep output of a neural network normalized.
* @example
* let { methods, Network } = require("@liquid-carrot/carrot");
*
* let myNetwork = new Network(5, 10, 5);
*
* myNetwork.mutate(methods.mutation.SWAP_NODES);
*/
SWAP_NODES: {
name: 'SWAP_NODES',
mutateOutput: false,
},
};
/**
*
* Array of all mutation methods
*
* @constant
* @type {array}
* @default
*
* @example <caption>A group of mutation methods for evolution</caption>
* let { methods, Network } = require("@liquid-carrot/carrot");
*
* let myNetwork = new Network(5, 10, 5);
*
* network.evolve(trainingset, {
* mutation: methods.mutation.ALL // all mutation methods
* }
*/
mutation.ALL = [
mutation.ADD_NODE,
mutation.SUB_NODE,
mutation.ADD_CONN,
mutation.SUB_CONN,
mutation.MOD_WEIGHT,
mutation.MOD_BIAS,
mutation.MOD_ACTIVATION,
mutation.ADD_GATE,
mutation.SUB_GATE,
mutation.ADD_SELF_CONN,
mutation.SUB_SELF_CONN,
mutation.ADD_BACK_CONN,
mutation.SUB_BACK_CONN,
mutation.SWAP_NODES,
];
/**
*
* Array of all feedforwad mutation methods
*
* @constant
* @type {array}
* @default
*
* @example <caption>A group of mutation methods for evolution</caption>
* let { methods, Network } = require("@liquid-carrot/carrot");
*
* let myNetwork = new Network(5, 10, 5);
*
* network.evolve(trainingset, {
* mutation: methods.mutation.FFW// all feedforward mutation methods
* }
*/
mutation.FFW = [
mutation.ADD_NODE,
mutation.SUB_NODE,
mutation.ADD_CONN,
mutation.SUB_CONN,
mutation.MOD_WEIGHT,
mutation.MOD_BIAS,
mutation.MOD_ACTIVATION,
mutation.SWAP_NODES,
];
module.exports = mutation;
