# Immortal Jellyfish Algorithm: a four-phase Python optimizer that cycles instead of converging once

> IJA is a metaheuristic optimizer modelled on the Turritopsis dohrnii lifecycle, shipped in Python, C++ and Java under MIT. It is a research artifact with a narrow audience, and the README's own benchmark setup is the first thing to question.

**LangZhong36/immortal-jellyfish-algorithm** — A novel bio-inspired swarm intelligence optimizer — immortal Jellyfish Algorithm (IJA)

- Repository: https://github.com/LangZhong36/immortal-jellyfish-algorithm
- Stars: 492 · Forks: 66
- Language: Python
- License: MIT
- Published: 2026-09-20 · Updated: 2026-09-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/langzhong36-immortal-jellyfish-algorithm

## The problem IJA claims to solve, and who actually needs it

Most swarm optimizers follow one arc: explore widely early, converge tightly late, then stop. The Immortal Jellyfish Algorithm instead schedules four distinct behaviours across normalized time and, at the end, refines rather than freezes. The README frames this as modelling Turritopsis dohrnii, the jellyfish that can revert from adult medusa to juvenile polyp, plus the inverse-square falloff of light from a point source.

That framing tells you the audience. This is a research artifact for people who compare metaheuristics: the repository ships an 8-function benchmark suite, a comparison module containing PSO, DE, GWO, WOA and SCA, and an experiment runner that the README describes as 30 runs across 6 algorithms and 8 functions. If your job is to pick a solver for a scheduling or tuning problem, the lifecycle metaphor is not a reason to choose it. If your job is to publish or reproduce optimizer comparisons, the four-phase schedule is the interesting part.

## How the four-phase lifecycle actually drives the search

The README gives a phase diagram over tau = t / T_max with four intervals. From 0 to 0.15 the population is in POLYP and runs Levy-flight exploration. From 0.15 to 0.50, STROBILATION produces adaptive ephyra buds, described as diversification. From 0.50 to 0.85, MEDUSA applies lighthouse attraction, the convergence phase. From 0.85 to 1, SENESCENCE applies Gaussian refinement.

Three operators carry the mathematics. Lighthouse attraction weights each elite by I_0 / (1 + kappa * ||x_i - g_s||^2) times e^(-lambda * tau), so influence decays both with distance and with time. Levy exploration moves a candidate by 0.01 * (u - l) * L_j(beta) * (x_i - x*), a standard Levy step scaled to the variable range. Pulsed swimming adds a sinusoidal displacement A_0 * (1 - tau)^2 * sin(2*pi*f_p*tau + phi_i) * (u_j - l_j), with amplitude shrinking as the run progresses.

The repository layout in the README names the machinery: python/ija/operators.py holds the operators, lifecycle.py holds the phase scheduler, and archive.py implements a crowding-distance elite archive. That archive is what makes the cycling meaningful. Elites persist across phase changes instead of being discarded when the population moves on.

## Installing the Python package and running a first optimization

The README's Python quick start installs dependencies from requirements.txt, then imports IJA from the python directory by inserting it on sys.path. The package is not described as published to PyPI; pyproject.toml declares the name immortal-jellyfish-algorithm with setuptools finding packages under python, but the README's own instructions use the path insert instead.

Install the dependencies first:

```bash
pip install -r requirements.txt
```

requirements.txt lists numpy, matplotlib, scipy and tqdm. Only numpy is a hard dependency in pyproject.toml; scipy, tqdm and matplotlib sit in the experiments, visualize and all optional groups.

The README's minimal run minimizes the sphere function in 30 dimensions with a population of 100 over 2000 iterations:

```python
import sys; sys.path.insert(0, "python")
from ija import IJA
import numpy as np

result = IJA(n=100, max_iter=2000, seed=0).optimize(
    lambda x: np.sum(x**2), dim=30, lb=-100.0, ub=100.0
)
print(f"Best fitness : {result.best_fitness:.6e}")
print(f"NFev         : {result.n_function_evals}")
```

The result object exposes best_fitness and n_function_evals, so you can check the evaluation count against your own budget rather than assuming it. The seed argument makes the run reproducible. A longer example lives at python/examples/quickstart.py. The C++ build uses cmake with -DCMAKE_BUILD_TYPE=Release and runs ./ija_demo; the Java build uses mvn compile and mvn exec:java with main class ija.Main.

## The benchmark table is the weakest part of the README

The README states that experiments used 30 independent runs at dimension D = 30, and then adds a sentence that should stop a careful reader: IJA uses recommended settings while competitors use standard or published settings. That is a fairness problem, not a detail. If IJA runs at n = 100 and max_iter = 2000 while a competitor runs at its own published defaults, the comparison measures parameter tuning as much as algorithm design.

Nothing in the README reports the competitors' population sizes or iteration budgets, and no release was retrieved for this repository, so there is no changelog to check whether the protocol changed. The figures referenced (results/convergence_curves.png, rank_heatmap.png, average_rank_bar.png, boxplots.png) are images; a reader cannot inspect the underlying numbers without running python/experiments/run_all.py themselves. Treat the ranking as a claim to reproduce, not a result to cite.

The parameter table is more useful than the plots. It documents top_k = 5 lighthouse elites, levy_beta = 1.5, archive_size = 20, age_max = 20 as a stagnation threshold, decay_lambda = 0.3, and alpha_max / alpha_min at 2.5 and 0.01. Those are the knobs you would actually tune, and they are stated plainly.

## Where IJA is the wrong tool

IJA is a derivative-free, population-based global optimizer. It assumes your objective can be evaluated as a function of a real-valued vector inside box bounds, and it assumes you can afford roughly n times max_iter evaluations. At the recommended settings that is on the order of 200,000 evaluations per run, before you multiply by 30 runs for a study. If each evaluation is an expensive simulation, that budget is the constraint, not the algorithm.

The README documents no constraint handling, no integer or mixed-variable support, and no parallel or distributed execution. The optimize signature takes dim, lb and ub, which describes a continuous box-constrained problem. If your problem is combinatorial, or has hard equality constraints, nothing in the repository addresses it.

There is also a maturity signal in the packaging. pyproject.toml points both Homepage and Repository at github.com/YOUR_USERNAME/immortal-jellyfish-algorithm, a placeholder that was never replaced. The README's citation block uses the year 2025 and author IJA Contributors. The last push to the default branch was on 2026-06-27, so the repository is not archived but has been quiet for roughly three months. For a research codebase that is normal; for a dependency you would vendor into a product, it means you are the maintainer.

## How IJA differs from PSO, DE and GWO

The repository itself ships the alternatives: python/compare/algorithms.py contains PSO, DE, GWO, WOA and SCA. The practical difference is the time-varying schedule. Particle Swarm Optimization applies the same velocity update from the first iteration to the last, with inertia weight as the only decay mechanism. Differential Evolution applies mutation and crossover at a fixed rate unless you change it. Grey Wolf Optimization has a linearly decreasing control parameter that moves from exploration to exploitation once.

IJA instead swaps the update rule four times, and the swap points are fixed fractions of the run rather than adaptive triggers. That is the design bet: diversification is scheduled, not detected. The cost is that the boundaries at 0.15, 0.50 and 0.85 are hard-coded phase transitions; if your problem wants more exploration than the schedule allows, you have to change the schedule, not a parameter. The benefit is that the archive carries elites across those transitions, so a phase change does not throw away the best solution found so far.

If you want a well-understood baseline with decades of tuning literature, PSO or DE is the safer pick. If you want to test whether scheduled phase cycling beats fixed-rule search on your problem class, IJA is the thing to put in the comparison.

## Licence, maintenance and what an upgrade costs you

The project is MIT licensed, declared both in the README and in pyproject.toml as license = {file = "LICENSE"}. MIT permits use, modification and redistribution with the copyright notice retained. For a research optimizer that is the permissive end of the spectrum, and it means you can vendor python/ija/ into a proprietary codebase without a licensing discussion. This is a description of the licence text, not legal advice.

Upgrade cost is low in the sense that the Python package depends only on numpy at runtime, pinned at numpy>=1.21. There is no compiled extension, no service, and no migration path to plan. The version in pyproject.toml is 1.0.0, and no releases were retrieved, so version pinning from a package index is not something the README describes.

The real maintenance cost is the three-language commitment. The README's contributing section states that all three implementations should remain feature-equivalent. If you patch an operator in python/ija/operators.py, the C++ and Java trees are expected to follow. For a team that only needs Python, that is an obligation you inherit by forking rather than a service you receive.

## Conclusion

Adopt IJA if you are doing comparative metaheuristics research and want a fourth-phase optimizer to benchmark against PSO, DE, GWO, WOA and SCA using the same objective-function interface. Do not adopt it as production optimization infrastructure. Before trusting any number, verify that IJA and its competitors were run under the same budget and settings, because the README states IJA uses recommended settings while competitors use standard or published ones.

## FAQ

### How do I install the Immortal Jellyfish Algorithm in Python?

The README's quick start runs pip install -r requirements.txt, which lists numpy, matplotlib, scipy and tqdm. The example then adds the python directory to sys.path and imports IJA from ija, so the README does not describe installing it from a package index.

### Which algorithms does the Immortal Jellyfish Algorithm compare against in its benchmarks?

The repository's compare module contains PSO, DE, GWO, WOA and SCA, and the experiment runner is described as 30 runs across 6 algorithms and 8 functions. The README notes that IJA uses recommended settings while the competitors use standard or published settings.

### What are the recommended parameter values for the Immortal Jellyfish Algorithm?

The README's parameter table lists n = 100, max_iter = 2000, top_k = 5, levy_beta = 1.5, archive_size = 20, age_max = 20, decay_lambda = 0.3, alpha_max = 2.5 and alpha_min = 0.01. These are the values used in the documented benchmark runs.

### Is the Immortal Jellyfish Algorithm available in languages other than Python?

Yes. The README states it is available in Python, C++ and Java, with separate cpp/ and java/ directories. The contributing section says all three implementations should remain feature-equivalent.

### What licence does the Immortal Jellyfish Algorithm use?

It is MIT licensed. The README links to LICENSE, and pyproject.toml declares license = {file = "LICENSE"} with the classifier License :: OSI Approved :: MIT License.

## Sources

- [Issues](https://github.com/LangZhong36/immortal-jellyfish-algorithm/issues)
- [LangZhong36/immortal-jellyfish-algorithm on GitHub](https://github.com/LangZhong36/immortal-jellyfish-algorithm)
- [License: MIT](https://github.com/LangZhong36/immortal-jellyfish-algorithm/blob/main/LICENSE)
- [README](https://github.com/LangZhong36/immortal-jellyfish-algorithm/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/langzhong36-immortal-jellyfish-algorithm