Skip to main content

MetaGen: A Framework for Metaheuristic Development and Hyperparameter Optimization

Python PyPI Latest Release CI Documentation License: GPL v3

🚀 Why MetaGen?

MetaGen simplifies the development of metaheuristics and the optimization of hyperparameters in machine learning and deep learning. Whether you're a researcher, developer, or practitioner, MetaGen provides a structured, flexible, and scalable framework.

🔹 Key Features

✔ Metaheuristic Development Framework – A base class with the run loop, elitism and callbacks; you write three methods.
✔ Hyperparameter Optimization Tools – Search spaces with integers, reals, categoricals, permutations, subsets, groups and variable-length structures, conditional variables that apply only for some values of another, and a range per position of a structure, for layer and architecture-level tuning.
✔ Standardized Interface – Ensures compatibility between metaheuristic developers and end users.
✔ Dynamic Architecture Optimization – Structures whose length the search itself changes.
✔ Seamless Integration – Compatible with scikit-learn, tensorflow, pytorch, and other ML libraries.
✔ Built-in Metaheuristics – Pre-implemented algorithms ready to use.
✔ Reproducible Runs – A seed parameter controls every random draw, also across Ray workers.
✔ Pause and Resume – Give a run a checkpoint file and it continues where it stopped after a power failure or a job scheduler's time limit, with the same result as an uninterrupted run.
✔ Run History and TensorBoard – Every run keeps a record of each iteration, which it can write as a JSON Lines file for pandas; give it a log_dir and follow it graphically in TensorBoard.
✔ Scalable and Distributed Execution – With distributed=True, metaheuristics run across the CPUs of a Ray cluster.
✔ Budgets and Racing – Stop a run after a number of evaluations or seconds and, with racing, stop evaluating a candidate as soon as it is significantly worse than the population.
✔ Reports – An HTML page or a PDF with the parameters, the convergence and the cost of a run, or of several runs side by side.
✔ Triclustering – TriGen finds blocks of three-dimensional data whose values behave alike, such as genes under some conditions at some times or regions of a series of images, with measures of quality, biological enrichment and synthetic data to check a search against.

📌 Built-in Metaheuristics

  • Random Search
  • Hill Climbing
  • Tabu Search
  • Simulated Annealing
  • Genetic Algorithm and Steady-State Genetic Algorithm
  • Memetic Algorithm
  • Tree-structured Parzen Estimator: TPE, which evaluates a pool of candidates per iteration, and KernelTPE, which evaluates a single candidate per iteration, for expensive fitness functions
  • Coronavirus Optimization Algorithm (CVOA), with two strain classes, CVOA and ProbabilisticCVOA, that differ in how deaths, superspreaders and isolation are decided
  • TriGen, a genetic algorithm that finds triclusters in three-dimensional data

The documentation has a guide to choosing one, with what each costs in evaluations.

📦 Installation

MetaGen requires Python 3.10+ and can be installed with:

pip install pymetagen-datalabupo

Some features are optional and installed on demand:

pip install pymetagen-datalabupo[distributed]   # Ray, for distributed=True
pip install pymetagen-datalabupo[tensorboard]   # TensorBoard logging
pip install pymetagen-datalabupo[report]        # matplotlib, for the reports of a run
pip install pymetagen-datalabupo[netcdf]        # xarray and netCDF4, for NetCDF-4 cubes
pip install pymetagen-datalabupo[all]           # all of them

📖 Documentation

The official API reference and usage guides are available at: MetaGen Documentation

🤖 Example: Hyperparameter Optimization

Optimizing hyperparameters for a regression model:

from metagen.framework import Domain, Solution
from metagen.metaheuristics import RandomSearch
from sklearn.datasets import make_regression
from sklearn.linear_model import SGDRegressor
from sklearn.model_selection import cross_val_score

# Generate synthetic dataset
X, y = make_regression(n_samples=1000, n_features=4, random_state=0)

# Define the search space
regression_domain = Domain()
regression_domain.define_real("alpha", 0.0001, 0.001)
regression_domain.define_integer("iterations", 5, 200)
regression_domain.define_categorical("loss", ["squared_error", "huber", "epsilon_insensitive"])

# Fitness function: MetaGen always minimizes
def regression_fitness(solution: Solution) -> float:
    model = SGDRegressor(
        loss=solution["loss"],
        alpha=solution["alpha"],
        max_iter=solution["iterations"]
    )
    mape = cross_val_score(model, X, y, scoring="neg_mean_absolute_percentage_error").mean() * -1
    return mape

# Run optimization; the seed makes the run reproducible
best_solution = RandomSearch(regression_domain, regression_fitness, seed=0).run()
print(best_solution)

Any other metaheuristic takes the same two arguments. To follow the run in TensorBoard, add log_dir="logs/random_search" and launch tensorboard --logdir=logs; to see progress on the console, call set_metagen_logger_level() from metagen.logging.metagen_logger.

🛠 Example: Developing a Metaheuristic

Creating a simple Random Search metaheuristic:

from copy import deepcopy
from typing import Callable, List
from metagen.framework import Domain, Solution

class RandomSearch:

    def __init__(self, domain: Domain, fitness: Callable[[Solution], float], search_space_size: int = 30,
                iterations: int = 20) -> None:

        self.domain = domain
        self.fitness = fitness
        self.search_space_size = search_space_size
        self.iterations = iterations

    def run(self) -> Solution:

        potential_solutions: List[Solution] = list()

        for _ in range(0, self.search_space_size):
            potential_solutions.append(Solution(self.domain, connector=self.domain.get_connector()))

        solution: Solution = deepcopy(min(potential_solutions))

        for _ in range(0, self.iterations):
            for ps in potential_solutions:
                ps.mutate()

                ps.evaluate(self.fitness)
                if ps < solution:
                    solution = deepcopy(ps)

        return solution

A metaheuristic can also inherit from the Metaheuristic base class, which adds the run loop, elitism, seed, log_dir and distributed execution in exchange for three methods; see Extending the Metaheuristic class.

📝 Citing MetaGen

If you use MetaGen in your research, please cite:

D. Gutiérrez-Avilés, M. J. Jiménez-Navarro, J. F. Torres, F. Martínez-Álvarez. MetaGen: A framework for metaheuristic development and hyperparameter optimization in machine and deep learning. Neurocomputing 637 (2025) 130046. https://doi.org/10.1016/j.neucom.2025.130046

@article{metagen2025,
  title   = {MetaGen: A framework for metaheuristic development and hyperparameter optimization in machine and deep learning},
  author  = {Guti{\'e}rrez-Avil{\'e}s, David and Jim{\'e}nez-Navarro, Manuel Jes{\'u}s and Torres, Jos{\'e} Francisco and Mart{\'i}nez-{\'A}lvarez, Francisco},
  journal = {Neurocomputing},
  volume  = {637},
  pages   = {130046},
  year    = {2025},
  doi     = {10.1016/j.neucom.2025.130046}
}

The article describes version 0.2.0, which remains available on PyPI and as a tagged release.

🤝 Contributing

We welcome contributions from developers of all experience levels! To contribute:

  • Open an issue or submit a pull request.

  • Install the package for development and run the tests:

    pip install -e .[test]
    pytest test
    mypy src
    

    Both must pass; the continuous integration runs them on Python 3.10 to 3.12.

📌 Resources

⚖️ License

MetaGen is free software, distributed under the GNU General Public License v3 or later.


MetaGen is an open-source project developed and maintained by:

  • David Gutiérrez-Avilés
  • Manuel Jesús Jiménez-Navarro
  • Francisco José Torres-Maldonado
  • Francisco Martínez-Álvarez

The authors are members of the Minerva AI Lab Group at the University of Seville and of DataLabUPO, the Data Science & Big Data Research Lab at Pablo de Olavide University.

Metadata

Release files for pymetagen-datalabupo 1.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pymetagen-datalabupo 1.4.0
File Size Uploaded Provenance Actions
pymetagen_datalabupo-1.4.0.tar.gz 258.9 kB Without provenance Details for pymetagen_datalabupo-1.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pymetagen-datalabupo 1.4.0
File Interpreter ABI Platform Actions
pymetagen_datalabupo-1.4.0-py3-none-any.whl Python 3 none any Details for pymetagen_datalabupo-1.4.0-py3-none-any.whl

Total release size: 584.1 kB

Release files / pymetagen_datalabupo-1.4.0.tar.gz

Download URL pymetagen_datalabupo-1.4.0.tar.gz
Size 258.9 kB
Tags Source
SHA-256 checksum
How to use checksums
b161d12ea6bb31b440b46218f8888dac60b6f8ee867cd4ad297932b28f12470c
BLAKE2b-256 checksum
How to use checksums
d560266a8692c1e0f64e701c09d391d500eaa197a1abe8d27a79a57d66d91a90
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.18

Release files / pymetagen_datalabupo-1.4.0-py3-none-any.whl

Download URL pymetagen_datalabupo-1.4.0-py3-none-any.whl
Size 325.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
25811c9b344c91875de8bacb946112d35e692ed37a8c4eb0b4d28ae14c732883
BLAKE2b-256 checksum
How to use checksums
f453e888b9454e52238a507046f0f9cb96278a1097d6cd2c2ad6e9cd0a7ca502
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.18

Security for pymetagen-datalabupo 1.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page