# erickfmm/anmetal architecture

> Architecture diagram of the GitHub repository erickfmm/anmetal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/erickfmm/anmetal
- Repository: https://github.com/erickfmm/anmetal

## Overview

##### Project Type and Purpose
- This is a Python library (“anmetal”) for numeric optimization and metaheuristics.
- It offers iterative methods (one-solution optimizers) and a suite of population-based metaheuristic algorithms, plus a collection of benchmark problems (NP-hard tasks, nonlinear functions) and utility functions (binarization, repair strategies).

##### High-Level Architecture
a. Interfaces Layer
- IMetaheuristic
- ISolution
- IProblem
b. Core Modules
- iterative_methods (one-solution methods: Euler, Newton)
- population (subpackages for ABC, ACO, PSO, GA, etc.)
c. Problems Layer
- nonlinear_functions (1-D, 2-D, N-D)
- nphard_real (partition, subset)
- nphard_categorical (knapsack, sudoku)
d. Utils Layer
- binarization_float, binarization_strategy
- points_utils
e. Consumer/Test Layer
- test and tests folders, which import the above modules to validate and demonstrate usage.

##### Component Identification and Relationships
- The population submodules implement IMetaheuristic and produce ISolution instances.
- Each algorithm class in population/… calls into problem objects (IProblem), passing objective_function, repair_function, preprocess_function.
- Problems modules implement IProblem; they expose methods and properties (min_x, max_x, ndim, objective_function, repair_function).
- iterative_methods is independent but sits alongside population (both use ISolution or raw numeric data).
- utils modules are dependencies of both population and problems for operations like binarization and point conversions.

- population → Interfaces (implements IMetaheuristic, ISolution)
- problems → Interfaces (implements IProblem)
- population → problems (calls objective_function)
- population & problems → utils (use binarization, point utilities)
- tests → all modules (import and validate)

##### Architectural Patterns and Principles
- Inversion of Control via interfaces (IMetaheuristic, IProblem) to allow plugging in any algorithm/problem.
- Separation of concerns: algorithms, problem definitions, utilities.
- Extensibility points: adding a new metaheuristic under population or a new problem under problems.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Interfaces Layer
    subgraph "Interfaces Layer"
        IMETA["IMetaheuristic"]:::interfaces
        ISOL["ISolution"]:::interfaces
        IPROB["IProblem"]:::interfaces
    end

    %% Core Modules
    subgraph "Core Modules"
        ITER["iterative_methods"]:::core
        subgraph Population
            ABC["ABC"]:::core
            ACO["Ant Colony (ACO)"]:::core
            AFSA["AFSA"]:::core
            BAT["Bat"]:::core
            BH["Blackhole"]:::core
            CUCKOO["Cuckoo"]:::core
            FIREFLY["Firefly"]:::core
            subgraph Genetic
                GENCAT["Genetic (categorical)"]:::core
            end
            HARMONY["Harmony Search"]:::core
            subgraph PSO
                PSO_REAL["PSO (real)"]:::core
                PARTICLE["Particle"]:::core
            end
            subgraph SillyRandom
                SILLY["SillyRandom (greedy real)"]:::core
            end
        end
    end

    %% Problems Layer
    subgraph "Problems Layer"
        subgraph Nonlinear Functions
            ONEIN["one_input"]:::problems
            TWOIN["two_inputs"]:::problems
            NIN["n_inputs"]:::problems
        end
        NP_REAL["Partition & Subset Sum"]:::problems
        subgraph "NP-Hard Categorical"
            KNAP["Knapsack"]:::problems
            SUDOKU["Sudoku"]:::problems
        end
    end

    %% Utils Layer
    subgraph "Utils Layer"
        BIN_FLOAT["binarization_float"]:::utils
        BIN_STRAT["binarization_strategy"]:::utils
        POINTS["points_utils"]:::utils
    end

    %% Tests/Consumer Layer
    subgraph "Tests/Consumer Layer"
        subgraph "Pytest-based Examples"
            TEST1["basic_math_it_optimization.py"]:::tests
            TEST2["basic_mh_optimization_npcomp.py"]:::tests
            TEST3["categorical_mh_optimization.py"]:::tests
            TEST4["mh_graph_each_it.py"]:::tests
            TEST5["nonlinear_mh_optimization.py"]:::tests
        end
        subgraph "Unit Tests"
            UTEST1["test_algorithms.py"]:::tests
            UTEST2["test_problems.py"]:::tests
        end
    end

    %% Relationships
    ABC -.-> IMETA
    ABC -.-> ISOL
    ACO -.-> IMETA
    AFSA -.-> IMETA
    BAT -.-> IMETA
    BH -.-> IMETA
    CUCKOO -.-> IMETA
    FIREFLY -.-> IMETA
    GENCAT -.-> IMETA
    HARMONY -.-> IMETA
    PSO_REAL -.-> IMETA
    SILLY -.-> IMETA

    ABC -->|calls objective_function| ONEIN
    ABC -->|calls objective_function| TWOIN
    ABC -->|calls objective_function| NIN
    ABC -->|calls objective_function| NP_REAL
    ABC -->|calls objective_function| KNAP
    ABC -->|calls objective_function| SUDOKU

    ABC -->|uses| BIN_FLOAT
    ABC -->|uses| BIN_STRAT
    ONEIN -->|uses| POINTS

    TEST1 --> ITER
    TEST2 --> ABC
    TEST3 --> GENCAT
    TEST5 --> NIN
    UTEST1 --> ABC
    UTEST2 --> KNAP

    %% Click Events
    click IMETA "https://github.com/erickfmm/anmetal/blob/master/src/anmetal/population/IMetaheuristic.py"
    click ISOL "https://github.com/erickfmm/anmetal/blob/master/src/anmetal/population/ISolution.py"
    click IPROB "https://github.com/erickfmm/anmetal/blob/master/src/anmetal/problems/IProblem.py"
    click ITER "https://github.com/erickfmm/anmetal/blob/master/src/anmetal/iterative_methods.py"
    click ABC "https://github.com/erickfmm/anmetal/blob/master/src/anmetal/population/ABC/abc.py"
    click AFSA "https://github.com/erickfmm/anmetal/blob/master/src/anmetal/population/AFSA/AFSAMH_Real.py"
    click ACO "https://github.com/erickfmm/anmetal/blob/master/src/anmetal/population/AntColony/aco.py"
    click BAT "https://github.com/erickfmm/anmetal/blob/master/src/anmetal/population/Bat/bat.py"
    click BH "https://github.com/erickfmm/anmetal/blob/master/src/anmetal/population/Blackhole/blackhole.py"
    click CUCKOO "https://github.com/erickfmm/anmetal/blob/master/src/anmetal/population/Cuckoo/cuckoo.py"
    click FIREFLY "https://github.com/erickfmm/anmetal/blob/master/src/anmetal/population/Firefly/firefly.py"
    click GENCAT "https://github.com/erickfmm/anmetal/blob/master/src/anmetal/population/Genetic/GeneticMH_Categorical.py"
    click HARMONY "https://github.com/erickfmm/anmetal/blob/master/src/anmetal/population/HarmonySearch/harmony.py"
    click PSO_REAL "https://github.com/erickfmm/anmetal/blob/master/src/anmetal/population/PSO/PSOMH_Real.py"
    click PARTICLE "https://github.com/erickfmm/anmetal/blob/master/src/anmetal/population/PSO/Particle.py"
    click SILLY "https://github.com/erickfmm/anmetal/blob/master/src/anmetal/population/SillyRandom/GreedyMH_Real.py"
    click ONEIN "https://github.com/erickfmm/anmetal/blob/master/src/anmetal/problems/nonlinear_functions/one_input.py"
    click TWOIN "https://github.com/erickfmm/anmetal/blob/master/src/anmetal/problems/nonlinear_functions/two_inputs.py"
    click NIN "https://github.com/erickfmm/anmetal/blob/master/src/anmetal/problems/nonlinear_functions/n_inputs.py"
    click NP_REAL "https://github.com/erickfmm/anmetal/blob/master/src/anmetal/problems/nphard_real/partition__and_subset_sum.py"
    click KNAP "https://github.com/erickfmm/anmetal/blob/master/src/anmetal/problems/nphard_categorical/knapsack.py"
    click SUDOKU "https://github.com/erickfmm/anmetal/blob/master/src/anmetal/problems/nphard_categorical/sudoku.py"
    click BIN_FLOAT "https://github.com/erickfmm/anmetal/blob/master/src/anmetal/utils/binarization_float.py"
    click BIN_STRAT "https://github.com/erickfmm/anmetal/blob/master/src/anmetal/utils/binarization_strategy.py"
    click POINTS "https://github.com/erickfmm/anmetal/blob/master/src/anmetal/utils/points_utils.py"
    click TEST1 "https://github.com/erickfmm/anmetal/blob/master/test/basic_math_it_optimization.py"
    click TEST2 "https://github.com/erickfmm/anmetal/blob/master/test/basic_mh_optimization_npcomp.py"
    click TEST3 "https://github.com/erickfmm/anmetal/blob/master/test/categorical_mh_optimization.py"
    click TEST4 "https://github.com/erickfmm/anmetal/blob/master/test/mh_graph_each_it.py"
    click TEST5 "https://github.com/erickfmm/anmetal/blob/master/test/nonlinear_mh_optimization.py"
    click UTEST1 "https://github.com/erickfmm/anmetal/blob/master/tests/test_algorithms.py"
    click UTEST2 "https://github.com/erickfmm/anmetal/blob/master/tests/test_problems.py"

    %% Styles
    classDef interfaces fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef core fill:#90EE90,stroke:#333,stroke-width:1px
    classDef problems fill:#FFFFE0,stroke:#333,stroke-width:1px
    classDef utils fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef tests fill:#F08080,stroke:#333,stroke-width:1px
```
