genetic-search/es/genetic.d.ts

Multiprocessing genetic algorithm implementation library

import type { GeneticSearchConfig, GeneticSearchStrategyConfig, GeneticSearchInterface, GenerationFitnessColumn, Population, BaseGenome, GeneticSearchFitConfig, ComposedGeneticSearchConfig, IdGeneratorInterface, PhenomeCacheInterface, GenomeStatsManagerInterface, PopulationSummaryManagerInterface, PopulationSummary, SchedulerInterface, EvaluatedGenome } from "./types";
import { IdGenerator } from "./utils";
/**
 * A genetic search algorithm.
 *
 * @template TGenome The type of genome objects in the population.
 *
 * @remarks
 * This class implements the genetic search algorithm. The algorithm is
 * configured using the [[GeneticSearchConfig]] object.
 *
 * The algorithm uses the following components, which can be customized by
 * providing a custom implementation:
 *
 * - A [[PopulateStrategyInterface]] to generate the initial population.
 * - A [[MutationStrategyInterface]] to mutate the population.
 * - A [[CrossoverStrategyInterface]] to cross over the population.
 * - A [[PhenomeStrategyInterface]] to calculate the phenome of the population.
 * - A [[FitnessStrategyInterface]] to calculate the fitness of the population.
 * - A [[PhenomeCacheInterface]] to cache the phenome of the population.
 *
 * @category Genetic Algorithm
 */
export declare class GeneticSearch<TGenome extends BaseGenome> implements GeneticSearchInterface<TGenome> {
    protected readonly config: GeneticSearchConfig;
    protected readonly strategy: GeneticSearchStrategyConfig<TGenome>;
    protected readonly idGenerator: IdGeneratorInterface<TGenome>;
    protected readonly genomeStatsManager: GenomeStatsManagerInterface<TGenome>;
    protected readonly populationSummaryManager: PopulationSummaryManagerInterface<TGenome>;
    protected _generation: number;
    protected _population: Population<TGenome>;
    protected _populationBuffer: Population<TGenome>;
    /**
     * Constructs a new instance of the GeneticSearch class.
     *
     * @param config - The configuration for the genetic search.
     * @param strategy - The strategy configuration for genetic operations.
     * @param idGenerator - An optional ID generator for the genomes.
     */
    constructor(config: GeneticSearchConfig, strategy: GeneticSearchStrategyConfig<TGenome>, idGenerator?: IdGeneratorInterface<TGenome>);
    /**
     * The current generation number.
     *
     * @returns The current generation number.
     */
    get generation(): number;
    /**
     * Gets the best genome from the population.
     *
     * @returns The best genome from the population.
     */
    get bestGenome(): TGenome;
    /**
     * The current population of genomes.
     *
     * @returns The current population of genomes.
     */
    get population(): Population<TGenome>;
    /**
     * Sets the current population of genomes.
     *
     * @param population The new population of genomes.
     */
    set population(population: Population<TGenome>);
    /**
     * Sets the current population of genomes.
     *
     * @param population The new population of genomes.
     * @param resetIdGenerator Whether to reset the ID generator. Defaults to true.
     */
    setPopulation(population: Population<TGenome>, resetIdGenerator?: boolean): void;
    /**
     * Calculates and returns the partitions of the population for the genetic operations.
     *
     * @returns A tuple containing:
     * - The number of genomes that will survive.
     * - The number of genomes that will be created by crossover.
     * - The number of genomes that will be created by mutation.
     */
    get partitions(): [number, number, number];
    /**
     * Retrieves the phenome cache used by the genetic search algorithm.
     *
     * @returns {PhenomeCacheInterface} The phenome cache instance.
     */
    get cache(): PhenomeCacheInterface;
    /**
     * Retrieves the population summary, optionally rounding the statistics to a specified precision.
     *
     * @param roundPrecision Optional. The number of decimal places to round the summary statistics to.
     *                       If not provided, no rounding is applied.
     * @returns The population summary, with statistics rounded to the specified precision if provided.
     */
    getPopulationSummary(roundPrecision?: number): PopulationSummary;
    /**
     * Runs the genetic search algorithm.
     *
     * @param config The configuration for the genetic search algorithm.
     * @returns A promise that resolves when the algorithm has finished running.
     */
    fit(config: GeneticSearchFitConfig<TGenome>): Promise<void>;
    /**
     * Runs a single step of the genetic search algorithm.
     *
     * @param scheduler Optional. The scheduler to use for the genetic search algorithm.
     * @returns A promise that resolves with the fitness of the best genome in the population.
     */
    fitStep(scheduler?: SchedulerInterface<TGenome>): Promise<GenerationFitnessColumn>;
    /**
     * Clears the cache.
     *
     * @remarks
     * This method clears the cache, which is used to store the phenome of the genomes.
     * The cache is used to avoid re-calculating the phenome of the genomes if they remain unchanged.
     */
    clearCache(): void;
    /**
     * Refreshes the population.
     *
     * @remarks
     * This method is used to refresh the population, which is the array of genomes that are currently being evaluated.
     * The population is refreshed by swapping the current population with the population buffer.
     */
    refreshPopulation(): void;
    /**
     * Crosses the given input population.
     *
     * @param input The population of genomes to cross.
     * @param count The number of new genomes to create.
     * @returns An array of new genomes created by crossing the input population.
     */
    protected crossover(input: Array<EvaluatedGenome<TGenome>>, count: number): Population<TGenome>;
    /**
     * Mutates the given input population.
     *
     * @param input The population of genomes to mutate.
     * @param count The number of new genomes to create.
     * @returns An array of new genomes created by mutating the input population.
     */
    protected mutate(input: Array<EvaluatedGenome<TGenome>>, count: number): Population<TGenome>;
    /**
     * Refreshes the population buffer from the evaluated population.
     *
     * @param input The population of genomes to refresh the population buffer with.
     */
    protected refreshPopulationBuffer(input: Array<EvaluatedGenome<TGenome>>): void;
}
/**
 * A composed genetic search algorithm that combines multiple genetic search strategies.
 *
 * @template TGenome The type of genome objects in the population.
 *
 * @remarks
 * This class implements a composite genetic search algorithm that utilizes multiple
 * genetic search strategies, including eliminators and a final strategy. The algorithm
 * is configured using the [[ComposedGeneticSearchConfig]] object.
 *
 * The algorithm integrates the following components, which can be customized by
 * providing custom implementations:
 *
 * - A [[GeneticSearchStrategyConfig]] to define the strategy for the genetic operations.
 * - An [[IdGeneratorInterface]] to generate unique IDs for the genomes.
 *
 * @category Genetic Algorithm
 */
export declare class ComposedGeneticSearch<TGenome extends BaseGenome> implements GeneticSearchInterface<TGenome> {
    private readonly strategy;
    private readonly eliminators;
    private readonly final;
    private readonly idGenerator;
    private readonly config;
    /**
     * Constructs a new instance of the ComposedGeneticSearch class.
     *
     * @param config - The configuration for the composed genetic search algorithm.
     * @param strategy - The strategy configuration for genetic operations.
     * @param idGenerator - An optional ID generator for the genomes.
     */
    constructor(config: ComposedGeneticSearchConfig, strategy: GeneticSearchStrategyConfig<TGenome>, idGenerator?: IdGenerator<TGenome>);
    /**
     * The current generation number.
     *
     * @returns The current generation number.
     */
    get generation(): number;
    /**
     * Gets the best genome from the population.
     *
     * @returns The best genome from the population.
     */
    get bestGenome(): TGenome;
    /**
     * The current population of genomes.
     *
     * @returns The current population of genomes.
     */
    get population(): Population<TGenome>;
    set population(population: Population<TGenome>);
    /**
     * Sets the current population of genomes.
     *
     * @param population The new population of genomes.
     * @param resetIdGenerator Whether to reset the ID generator. Defaults to true.
     */
    setPopulation(population: Population<TGenome>, resetIdGenerator?: boolean): void;
    /**
     * Calculates and returns the partitions of the population for the genetic operations.
     *
     * @returns A tuple containing:
     * - The number of genomes that will survive.
     * - The number of genomes that will be created by crossover.
     * - The number of genomes that will be created by mutation.
     */
    get partitions(): [number, number, number];
    /**
     * Retrieves the phenome cache used by the genetic search algorithm.
     *
     * @returns {PhenomeCacheInterface} The phenome cache instance.
     */
    get cache(): PhenomeCacheInterface;
    /**
     * Retrieves the population summary, optionally rounding the statistics to a specified precision.
     *
     * @param roundPrecision Optional. The number of decimal places to round the summary statistics to.
     *                       If not provided, no rounding is applied.
     * @returns The population summary, with statistics rounded to the specified precision if provided.
     */
    getPopulationSummary(roundPrecision?: number): PopulationSummary;
    /**
     * Runs the genetic search algorithm.
     *
     * @param config The configuration for the genetic search algorithm.
     * @returns A promise that resolves when the algorithm has finished running.
     */
    fit(config: GeneticSearchFitConfig<TGenome>): Promise<void>;
    /**
     * Runs a single step of the genetic search algorithm.
     *
     * @param scheduler Optional. The scheduler to use for the genetic search algorithm.
     * @returns A promise that resolves with the fitness of the best genome in the population.
     */
    fitStep(scheduler?: SchedulerInterface<TGenome>): Promise<GenerationFitnessColumn>;
    /**
     * Clears the cache.
     *
     * @remarks
     * This method clears the cache, which is used to store the phenome of the genomes.
     * The cache is used to avoid re-calculating the phenome of the genomes if they remain unchanged.
     */
    clearCache(): void;
    /**
     * Refreshes the population.
     *
     * @remarks
     * This method is used to refresh the population, which is the array of genomes that are currently being evaluated.
     * The population is refreshed by swapping the current population with the population buffer.
     */
    refreshPopulation(): void;
    /**
     * Gets the best genomes from the eliminators.
     *
     * @remarks
     * This method returns the best genomes from each eliminator.
     * The best genomes are the genomes that have the highest fitness score.
     * The best genomes are determined by calling {@link GeneticSearch.bestGenome} on each eliminator.
     *
     * @returns The best genomes from the eliminators.
     */
    protected get bestGenomes(): Population<TGenome>;
}