fireworks-ts

A fully featured Fireworks Algorithm (FWA) optimization library in TypeScript.

Overview

The Fireworks Algorithm is a swarm intelligence optimization method inspired by the explosion of fireworks. Each "firework" represents a candidate solution in the search space. During each iteration, fireworks explode to produce sparks (new candidate solutions), with better fireworks producing more focused explosions and worse fireworks producing wider explorations. This balance between exploitation and exploration makes FWA effective for a wide range of optimization problems.

fireworks-ts provides three algorithm variants:

| Variant | Class | Paper | |---------|-------|-------| | FWA (2010) | FireworksAlgorithm | Tan, Y.; Zhu, Y. Fireworks Algorithm for Optimization. ICSI 2010. | | EFWA (2012) | FireworksAlgorithm2012 | Zheng, S.; Janecek, A.; Tan, Y. Enhanced Fireworks Algorithm. CEC 2012. | | dynFWA (2014) | DynamicFireworksAlgorithm | Zheng, S.; Tan, Y. Dynamic Search in Fireworks Algorithm. CEC 2014. |

The library is fully typed, tree-shakeable, and ships with ES module, CommonJS, and UMD bundles.

Installation

npm install fireworks-ts

Quick Start

import {
  Sphere,
  FireworksAlgorithm,
  FireworksAlgorithmSettings,
  StepCounterStopCondition,
  Randomizer,
  RandomizerType,
} from 'fireworks-ts';

// Use a built-in benchmark problem (10-dimensional sphere function)
const problem = Sphere.create();

// Configure the algorithm
const settings = new FireworksAlgorithmSettings();
settings.locationsNumber = 5;
settings.explosionSparksNumberModifier = 50;
settings.explosionSparksNumberLowerBound = 0.04;
settings.explosionSparksNumberUpperBound = 0.8;
settings.explosionSparksMaximumAmplitude = 40;
settings.specificSparksNumber = 5;
settings.specificSparksPerExplosionNumber = 1;

// Stop after 100 iterations
const stopCondition = new StepCounterStopCondition(100);

// Create a randomizer (Mersenne Twister)
const randomizer = new Randomizer(RandomizerType.MersenneTwister);

// Run the algorithm
const algorithm = new FireworksAlgorithm(problem, stopCondition, randomizer, settings);
const solution = algorithm.solve();

console.log('Best quality found:', solution.quality);

Algorithm Variants

FireworksAlgorithm (FWA 2010)

The original Fireworks Algorithm. Uses explosion sparks, Gaussian sparks, and distance-based location selection to maintain population diversity.

import {
  FireworksAlgorithm,
  FireworksAlgorithmSettings,
} from 'fireworks-ts';

const settings = new FireworksAlgorithmSettings();
settings.locationsNumber = 5;               // Number of fireworks (n)
settings.explosionSparksNumberModifier = 50; // Spark count modifier (m)
settings.explosionSparksNumberLowerBound = 0.04; // Lower bound (a)
settings.explosionSparksNumberUpperBound = 0.8;  // Upper bound (b)
settings.explosionSparksMaximumAmplitude = 40;   // Max amplitude (A)
settings.specificSparksNumber = 5;          // Gaussian sparks count
settings.specificSparksPerExplosionNumber = 1;

const algorithm = new FireworksAlgorithm(problem, stopCondition, randomizer, settings);
const solution = algorithm.solve();

FireworksAlgorithm2012 (Enhanced FWA)

Enhances the original with an elite strategy that uses polynomial fitting and root-finding to generate high-quality sparks. Replaces the worst firework with an elite spark when beneficial.

import {
  FireworksAlgorithm2012,
  FireworksAlgorithmSettings2012,
} from 'fireworks-ts';

const settings = new FireworksAlgorithmSettings2012();
settings.locationsNumber = 5;
settings.explosionSparksNumberModifier = 50;
settings.explosionSparksNumberLowerBound = 0.04;
settings.explosionSparksNumberUpperBound = 0.8;
settings.explosionSparksMaximumAmplitude = 40;
settings.specificSparksNumber = 5;
settings.specificSparksPerExplosionNumber = 1;
settings.functionOrder = 2;    // Polynomial order for fitness approximation
settings.samplingNumber = 10;  // Number of candidates to sample

const algorithm = new FireworksAlgorithm2012(problem, stopCondition, randomizer, settings);
const solution = algorithm.solve();

DynamicFireworksAlgorithm (dynFWA)

Introduces adaptive explosion amplitude for a tracked "core firework". When the core firework improves, its amplitude is amplified; otherwise it is reduced. This accelerates convergence while maintaining exploration.

import {
  DynamicFireworksAlgorithm,
  DynamicFireworksAlgorithmSettings,
} from 'fireworks-ts';

const settings = new DynamicFireworksAlgorithmSettings();
settings.locationsNumber = 5;
settings.explosionSparksNumberModifier = 50;
settings.explosionSparksNumberLowerBound = 0.04;
settings.explosionSparksNumberUpperBound = 0.8;
settings.explosionSparksMaximumAmplitude = 40;
settings.specificSparksNumber = 5;
settings.specificSparksPerExplosionNumber = 1;
settings.functionOrder = 2;
settings.samplingNumber = 10;
settings.amplificationCoefficent = 1.2;  // Amplify good explosions (C_a)
settings.reductionCoefficent = 0.9;      // Reduce poor explosions (C_r)

const algorithm = new DynamicFireworksAlgorithm(problem, stopCondition, randomizer, settings);
const solution = algorithm.solve();

Step-by-Step Execution

All algorithm variants support step-by-step execution for fine-grained control or visualization:

const algorithm = new FireworksAlgorithm(problem, stopCondition, randomizer, settings);

// Listen for step completion events
algorithm.addStepCompletedListener((args) => {
  console.log(`Step ${args.state.stepNumber}: best quality = ${args.state.bestSolution.quality}`);
});

// Manual step control
algorithm.initialize();
while (!algorithm.shouldStop()) {
  algorithm.makeStep();
}

Defining Custom Problems

import { Problem, ProblemTarget, Dimension, Interval } from 'fireworks-ts';

// Define a 2D search space
const dim1 = new Dimension(new Interval(-10, 10));
const dim2 = new Dimension(new Interval(-10, 10));
const dimensions = [dim1, dim2];

// Initial ranges for the first population (can differ from dimension ranges)
const initialRanges = new Map<Dimension, Interval>([
  [dim1, new Interval(-5, 5)],
  [dim2, new Interval(-5, 5)],
]);

// Target function to minimize
const targetFunction = (coords: Map<Dimension, number>): number => {
  const x = coords.get(dim1)!;
  const y = coords.get(dim2)!;
  return x * x + y * y; // Sphere function
};

const problem = new Problem(dimensions, initialRanges, targetFunction, ProblemTarget.Minimum);

Benchmark Problems

The library includes 12 standard benchmark optimization functions:

| Function | Class | Dimensions | Search Range | Known Best Quality | |----------|-------|------------|--------------|-------------------| | Sphere | Sphere | 10 | [-100, 100] | 0.0 | | Sphere (2012) | Sphere2012 | 10 | [-100, 100] | -450.0 | | Ackley | Ackley | 10 | [-5, 5] | 0.0 | | Rastrigin | Rastrigin | 2 | [-100, 100] | 0.0 | | Rosenbrock | Rosenbrock | 10 | [-100, 100] | 0.0 | | Griewank | Griewank | 10 | [-100, 100] | 0.0 | | Easom | Easom | 2 | [-100, 100] | 0.0 | | Beale | Beale | 2 | [-4.5, 4.5] | 0.0 | | Levi | Levi | 2 | [-10, 10] | 0.0 | | Ellipse | Ellipse | 10 | [-100, 100] | 0.0 | | Cigar | Cigar | 2 | [-100, 100] | 0.0 | | Tablet | Tablet | 10 | [-100, 100] | 0.0 |

All benchmark problems are created via a static create() factory method:

import { Sphere, Rosenbrock, Ackley } from 'fireworks-ts';

const sphere = Sphere.create();
const rosenbrock = Rosenbrock.create();
const ackley = Ackley.create();

Sphere2012 and Cigar support an optional shift parameter to move the optimum away from the origin:

const shifted = Sphere2012.create(true);

Stop Conditions

| Condition | Class | Description | |-----------|-------|-------------| | Counter | CounterStopCondition | Stops after a manually incremented counter reaches a threshold | | Step Counter | StepCounterStopCondition | Stops after a given number of algorithm steps | | Coordinate Proximity | CoordinateProximityStopCondition | Stops when the best solution's coordinates are close enough to a target | | Quality Proximity | QualityProximityStopCondition | Stops when the best solution's quality is close enough to a target | | Convergence | ConvergenceStopCondition | Stops when the best solution hasn't changed for N consecutive steps | | Chain | ChainStopCondition | Combines multiple conditions with AND/OR logic |

Chaining Stop Conditions

import {
  ChainStopCondition,
  StepCounterStopCondition,
  QualityProximityStopCondition,
  Solution,
} from 'fireworks-ts';

// Stop when quality is close enough to known best OR after 500 steps
const qualityStop = new QualityProximityStopCondition(new Solution(new Map(), 0.0), 0.001);
const maxSteps = new StepCounterStopCondition(500);

const stopCondition = ChainStopCondition.from(qualityStop).or(maxSteps);

Selection Strategies

| Strategy | Class | Description | |----------|-------|-------------| | Best | BestFireworkSelector | Selects the N best fireworks by quality | | Random | RandomFireworkSelector | Selects N fireworks at random | | Near Best | NearBestFireworkSelector | Selects fireworks closest to the best one | | Best + Random | BestAndRandomFireworkSelector | Always includes the best, fills rest randomly | | Distance-Based | DistanceBasedFireworkSelector | Probability-weighted by distance from others (2010 paper) | | Extremum | ExtremumFireworkSelector | Selects the single best or worst firework |

Spark Generators

| Generator | Class | Description | |-----------|-------|-------------| | Initial | InitialSparkGenerator | Creates the initial population | | Explosion (2010) | ExplosionSparkGenerator | Standard explosion sparks with coin-flip dimension selection | | Explosion (2012) | ExplosionSparkGenerator2012 | Modifies all dimensions (no coin flip) | | Gaussian (2010) | GaussianSparkGenerator | Gaussian mutation with coin-flip | | Gaussian (2012) | GaussianSparkGenerator2012 | Gaussian mutation on all dimensions | | Attract-Repulse | AttractRepulseSparkGenerator | Moves sparks toward/away from the best solution | | Dynamic Explosion | DynamicExplosionSparkGenerator | Randomizes out-of-range coordinates | | Elite (LS1) | LS1EliteSparkGenerator | Elite spark via midpoint search | | Elite (LS2) | LS2EliteSparkGenerator | Elite spark via polynomial differentiation and root-finding |

Settings Reference

FireworksAlgorithmSettings

| Property | Type | Description | |----------|------|-------------| | locationsNumber | number | Number of fireworks (n) | | explosionSparksNumberModifier | number | Spark count modifier (m) | | explosionSparksNumberLowerBound | number | Lower bound for spark count (a), 0 < a < b | | explosionSparksNumberUpperBound | number | Upper bound for spark count (b), a < b < 1 | | explosionSparksMaximumAmplitude | number | Maximum explosion amplitude (A) | | specificSparksNumber | number | Number of Gaussian sparks | | specificSparksPerExplosionNumber | number | Gaussian sparks per explosion |

FireworksAlgorithmSettings2012

Extends FireworksAlgorithmSettings with:

| Property | Type | Description | |----------|------|-------------| | functionOrder | number | Polynomial order for fitness landscape approximation | | samplingNumber | number | Number of candidates to sample before final selection |

DynamicFireworksAlgorithmSettings

Extends FireworksAlgorithmSettings2012 with:

| Property | Type | Description | |----------|------|-------------| | amplificationCoefficent | number | Amplitude amplification factor for improving core firework (C_a) | | reductionCoefficent | number | Amplitude reduction factor for non-improving core firework (C_r) |

Building from Source

# Install dependencies
npm install

# Build the library (TypeScript compilation + Vite bundling)
npm run build

# Run tests (Jest, 161 tests)
npm test

# Lint
npm run lint

# Format
npm run format

The build produces three output formats in dist/:

• fireworks-ts.es.js - ES module
• fireworks-ts.cjs.js - CommonJS
• fireworks-ts.umd.js - UMD (for script tags and CDNs)

TypeScript declaration files are included for full type support.

References

• Tan, Y.; Zhu, Y. Fireworks Algorithm for Optimization. Advances in Swarm Intelligence, ICSI 2010.
• Zheng, S.; Janecek, A.; Tan, Y. Enhanced Fireworks Algorithm. IEEE Congress on Evolutionary Computation, 2012.
• Zheng, S.; Tan, Y. Dynamic Search in Fireworks Algorithm. IEEE Congress on Evolutionary Computation, 2014.
• Li, J.; Tan, Y. GPU-Based Implementation of Fireworks Algorithm. Advances in Swarm Intelligence, ICSI 2013.

License

MIT - Copyright (c) 2024 Cipher Geist