Crate roma_lib 

Roma

roma is a Rust metaheuristics framework for optimization and experimentation.

It provides reusable building blocks to define optimization problems, configure algorithms, run reproducible executions, and observe progress through console or file-based reports.

Features

• Single-objective algorithms: Hill Climbing, Genetic Algorithm, Simulated Annealing, PSO.
• Multi-objective optimization with NSGA-II and Pareto rank/crowding quality metadata.
• Generic Problem and Solution abstractions for custom domains.
• Structured observers (console, chart, HTML report) and checkpoint utilities.
• Experiment runner for repeated case execution and comparative summaries.

Installation

[dependencies]
roma_lib = "0.1.1"

Quick Start

use roma_lib::algorithms::{
    Algorithm,
    HillClimbing,
    HillClimbingParameters,
    TerminationCriteria,
    TerminationCriterion,
};
use roma_lib::operator::BitFlipMutation;
use roma_lib::problem::KnapsackBuilder;
use roma_lib::solution_set::SolutionSet;

fn main() {
    let problem = KnapsackBuilder::new()
        .with_capacity(40.0)
        .add_items(vec![(4.0, 8.0), (7.0, 13.0), (5.0, 10.0), (3.0, 4.0)])
        .build();

    let params = HillClimbingParameters::new(
        BitFlipMutation::new(),
        0.15,
        TerminationCriteria::new(vec![TerminationCriterion::MaxIterations(50)]),
    )
    .with_seed(42);

    let mut algorithm = HillClimbing::new(params);
    let solutions = algorithm.run(&problem).expect("run should succeed");

    if let Some(best) = solutions.best_solution(&problem) {
        println!("best quality: {}", best.quality_value());
    }
}

Core Concepts

• Problem<T, Q> defines solution generation, evaluation, objective direction, and formatting.
• Solution<T, Q> stores decision variables and an optional quality cache.
• Algorithm<T, Q> executes a shared runtime lifecycle and returns a SolutionSet.
• Observers subscribe to runtime events and can render progress/summary outputs.
• Experiment runs multiple algorithm cases repeatedly and computes aggregate statistics.

Documentation

• API docs: https://docs.rs/roma
• Repository: https://github.com/DRLKs/roma

License

Licensed under either:

• MIT license
• Apache License, Version 2.0

at your option.

Architecture

Roma is organized around five core concepts:

• problem::Problem: domain definition and evaluation logic.
• solution::Solution: decision variables plus cached quality payload.
• algorithms::Algorithm: shared execution lifecycle for optimization methods.
• solution_set::SolutionSet: container abstraction for algorithm outputs.
• observer::AlgorithmObserver: event-based progress and reporting hooks.

Built-in implementations cover common mono-objective and multi-objective workflows.

Execution Lifecycle

All algorithms run through a single runtime contract:

1. initialize algorithm state,
2. emit snapshots to observers,
3. evaluate termination criteria,
4. finalize into a solution set.

This keeps observer behavior, checkpoint integration, and termination semantics consistent across algorithms.

Quick Start

use roma_lib::algorithms::{
    Algorithm,
    HillClimbing,
    HillClimbingParameters,
    TerminationCriteria,
    TerminationCriterion,
};
use roma_lib::operator::BitFlipMutation;
use roma_lib::problem::KnapsackBuilder;
use roma_lib::solution_set::SolutionSet;

let problem = KnapsackBuilder::new()
    .with_capacity(30.0)
    .add_items(vec![(4.0, 8.0), (6.0, 12.0), (10.0, 24.0)])
    .build();

let parameters = HillClimbingParameters::new(
    BitFlipMutation::new(),
    0.2,
    TerminationCriteria::new(vec![TerminationCriterion::MaxIterations(25)]),
)
.with_seed(7);

let mut algorithm = HillClimbing::new(parameters);
let result = algorithm.run(&problem)?;

let best = result
    .best_solution(&problem)
    .expect("solution set should not be empty");
assert!(best.quality_value().is_finite());

Where to Go Next

• Use prelude for ergonomic imports in applications and demos.
• Explore experiment::Experiment for repeated runs and comparative summaries.
• Use observer::ConsoleObserver, observer::ChartObserver, or observer::HtmlReportObserver for runtime visibility.

Re-exports

pub use algorithms::run_algorithm_instances_async;

pub use algorithms::run_algorithms_async;

pub use algorithms::spawn_algorithm_run;

pub use algorithms::Algorithm;

pub use algorithms::DifferentialEvolution;

pub use algorithms::DifferentialEvolutionParameters;

pub use algorithms::ExecutionStateSnapshot;

pub use algorithms::GeneticAlgorithm;

pub use algorithms::GeneticAlgorithmParameters;

pub use algorithms::HillClimbing;

pub use algorithms::HillClimbingParameters;

pub use algorithms::NSGAIIParameters;

pub use algorithms::PSOParameters;

pub use algorithms::SimulatedAnnealing;

pub use algorithms::SimulatedAnnealingParameters;

pub use algorithms::TabuSearch;

pub use algorithms::TabuSearchParameters;

pub use algorithms::TerminationController;

pub use algorithms::TerminationCriteria;

pub use algorithms::TerminationCriterion;

pub use algorithms::TerminationReason;

pub use algorithms::TerminationState;

pub use algorithms::VNSParameters;

pub use algorithms::NSGAII;

pub use algorithms::PSO;

pub use algorithms::VNS;

pub use experiment::Experiment;

pub use observer::AlgorithmEvent;

pub use observer::AlgorithmObserver;

pub use observer::ChartObserver;

pub use observer::ConsoleObserver;

pub use observer::HtmlReportObserver;

pub use observer::Observable;

pub use operator::BinaryTournamentSelection;

pub use operator::BitFlipMutation;

pub use operator::CrossoverOperator;

pub use operator::MultiObjectiveTournamentSelection;

pub use operator::MutationOperator;

pub use operator::Operator;

pub use operator::OrderCrossover;

pub use operator::PolynomialMutation;

pub use operator::RealPerturbationMutation;

pub use operator::SBXCrossover;

pub use operator::SelectionOperator;

pub use operator::SinglePointCrossover;

pub use operator::SwapMutation;

pub use problem::build_knapsack_from_records;

pub use problem::build_tsp_from_records;

pub use problem::AckleyProblem;

pub use problem::KnapsackBuilder;

pub use problem::KnapsackProblem;

pub use problem::Problem;

pub use problem::QapProblem;

pub use problem::TspProblem;

pub use problem::ZDT1Problem;

pub use solution::BinarySolutionBuilder;

pub use solution::MultiObjectiveRealSolutionBuilder;

pub use solution::MultiObjectiveVectorRealSolutionBuilder;

pub use solution::ParetoCrowdingDistanceQuality;

pub use solution::PermutationSolutionBuilder;

pub use solution::RealSolutionBuilder;

pub use solution::Solution;

pub use solution::StringSolutionBuilder;

pub use solution_set::DequeSolutionSet;

pub use solution_set::SolutionSet;

pub use solution_set::VectorSolutionSet;

pub use utils::delete_snapshot_on_success;

pub use utils::read_snapshot;

pub use utils::write_snapshot;

Modules

algorithms

Algorithm layer for optimization execution.

experiment

Experiment execution and reporting APIs.

observer

Observer system for algorithm execution events.

operator

Variation and selection operators used by algorithms.

prelude

Commonly used types and traits.

problem

Problem definitions and built-in benchmark/problem implementations.

solution

Core solution abstractions and builders.

solution_set

Containers and traits for algorithm output solution collections.

utils

Utility modules used across Roma.