# inesmcm26/cifo-24-25 architecture

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

- Interactive diagram: https://gitdiagram.com/inesmcm26/cifo-24-25
- Repository: https://github.com/inesmcm26/cifo-24-25

## Overview

##### Project type and purpose
- This is an educational, open-source Python library paired with Jupyter notebooks for teaching Computational Intelligence optimization algorithms (hill climbing, simulated annealing, genetic algorithms).
- The “library” folder contains all core algorithmic code; the two notebook folders contain “class” versions (empty cells for students) and “solution” versions (filled-in answers).

##### File structure
- Top-level:
- library/
- notebooks-class/
- notebooks-solution/
- requirements.txt
- library/ substructure:
- algorithms/ – various algorithm implementations
- problems/ – problem definitions and data sources
- solution.py, utils.py – common utilities and solution wrappers
- notebooks-class and notebooks-solution mirror each other by week, importing and exercising the library.
- No web server, persistence layer or external microservices—pure Python modules and Jupyter.

##### Key README insights
- Course repository; students edit notebooks-class, never touching notebooks-solution.
- The library is built incrementally from week to week.
- Dependencies managed via requirements.txt; run all code inside a Jupyter/Python environment.

##### Main components
a. Python environment / Jupyter kernel
b. Library component:
- Algorithms module
- hill_climbing.py
- simulated_annealing.py
- genetic_algorithms/ (algorithm.py, crossover.py, mutation.py, selection.py)
- Problems module
- problem classes (int_bin, int_max, tsp, ks)
- data sources (ks_data.py, tsp_data.py)
- Utils (utils.py) and Solution wrapper (solution.py)
c. Notebook clients:
- notebooks-class (empty cells)
- notebooks-solution (filled solutions)
d. External dependencies:
- Jupyter
- Python packages (NumPy, pandas, matplotlib, etc.)

##### Relationships & data flow
- Notebooks import Library → select a Problem → feed Problem to an Algorithm → Algorithm uses Utils → returns a Solution → Notebook visualizes results.

##### Architectural patterns & design principles
- Modular Python package: clear separation of concerns (algorithms vs. problem definitions vs. utilities).
- Incremental build: library evolves over time, used by versioned notebooks.
- No persistent storage or services—stateless computations within each notebook session.

2. Inside it, place:
– On the left: “notebooks-class” and “notebooks-solution” side by side.
3. Outside or adjacent: “requirements.txt → External Dependencies” listing libraries.
4. Connect:
- Library.Algorithms → Library.Utils (helper calls)
- Library → Notebooks (returns results)

##### Detail
- Don’t lump “algorithms” into a single block—show hill climbing, simulated annealing, and GA sub-modules.
- That genetic_algorithms itself has subcomponents (crossover, mutation, selection).
- That Problem classes encapsulate both the problem definition and the data they require.
- That notebooks are the user interface for running experiments and visualizing outputs.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Outer environment
    subgraph "Python / Jupyter Environment"
        direction TB

        %% Notebook clients
        notebooks_class["Notebooks - Class"]:::notebook
        notebooks_solution["Notebooks - Solution"]:::notebook

        %% Core Library
        subgraph "Library" 
            direction TB

            %% Algorithms Module
            subgraph "Algorithms" 
                direction TB
                hill["Hill Climbing"]:::library
                anneal["Simulated Annealing"]:::library
                subgraph "Genetic Algorithms" 
                    direction TB
                    ga_algo["algorithm.py"]:::library
                    ga_xover["crossover.py"]:::library
                    ga_mut["mutation.py"]:::library
                    ga_sel["selection.py"]:::library
                end
            end

            %% Problems Module
            subgraph "Problems" 
                direction TB
                intbin["int_bin.py"]:::library
                intmax["int_max.py"]:::library
                tsp_prob["tsp.py"]:::library
                ks_prob["ks.py"]:::library
                subgraph "Data Sources" 
                    direction TB
                    tsp_data["tsp_data.py"]:::data
                    ks_data["ks_data.py"]:::data
                end
            end

            %% Utilities & Solution
            utils["utils.py"]:::library
            solution["solution.py"]:::library
        end

        %% External Dependencies
        ext_dep["External Dependencies"]:::external

        %% Connections
        notebooks_class -->|"imports"| hill
        notebooks_class -->|"imports"| anneal
        notebooks_class -->|"imports"| ga_algo
        notebooks_solution -->|"imports"| hill
        notebooks_solution -->|"imports"| anneal
        notebooks_solution -->|"imports"| ga_algo

        hill -->|"calls helper"| utils
        anneal -->|"calls helper"| utils
        ga_algo -->|"calls helper"| utils
        ga_xover -->|"used by"| ga_algo
        ga_mut -->|"used by"| ga_algo
        ga_sel -->|"used by"| ga_algo

        intbin -->|"loads data"| ks_data
        intmax -->|"loads data"| ks_data
        tsp_prob -->|"loads data"| tsp_data
        ks_prob -->|"loads data"| ks_data
        solution -->|"wraps result"| notebooks_class
        solution -->|"wraps result"| notebooks_solution

        ext_dep -->|"specified in"| notebooks_class
        ext_dep -->|"specified in"| notebooks_solution

    end

    %% Click events
    click notebooks_class "https://github.com/inesmcm26/cifo-24-25/tree/main/notebooks-class/"
    click notebooks_solution "https://github.com/inesmcm26/cifo-24-25/tree/main/notebooks-solution/"
    click hill "https://github.com/inesmcm26/cifo-24-25/blob/main/library/algorithms/hill_climbing.py"
    click anneal "https://github.com/inesmcm26/cifo-24-25/blob/main/library/algorithms/simulated_annealing.py"
    click ga_algo "https://github.com/inesmcm26/cifo-24-25/blob/main/library/algorithms/genetic_algorithms/algorithm.py"
    click ga_xover "https://github.com/inesmcm26/cifo-24-25/blob/main/library/algorithms/genetic_algorithms/crossover.py"
    click ga_mut "https://github.com/inesmcm26/cifo-24-25/blob/main/library/algorithms/genetic_algorithms/mutation.py"
    click ga_sel "https://github.com/inesmcm26/cifo-24-25/blob/main/library/algorithms/genetic_algorithms/selection.py"
    click intbin "https://github.com/inesmcm26/cifo-24-25/blob/main/library/problems/int_bin.py"
    click intmax "https://github.com/inesmcm26/cifo-24-25/blob/main/library/problems/int_max.py"
    click tsp_prob "https://github.com/inesmcm26/cifo-24-25/blob/main/library/problems/tsp.py"
    click ks_prob "https://github.com/inesmcm26/cifo-24-25/blob/main/library/problems/ks.py"
    click tsp_data "https://github.com/inesmcm26/cifo-24-25/blob/main/library/problems/data/tsp_data.py"
    click ks_data "https://github.com/inesmcm26/cifo-24-25/blob/main/library/problems/data/ks_data.py"
    click utils "https://github.com/inesmcm26/cifo-24-25/blob/main/library/utils.py"
    click solution "https://github.com/inesmcm26/cifo-24-25/blob/main/library/solution.py"
    click ext_dep "https://github.com/inesmcm26/cifo-24-25/blob/main/requirements.txt"

    %% Styles
    classDef library fill:#bbdefb,stroke:#1e88e5,color:#0d47a1;
    classDef notebook fill:#c8e6c9,stroke:#388e3c,color:#1b5e20;
    classDef external fill:#e0e0e0,stroke:#9e9e9e,color:#424242;
    classDef data fill:#ffe0b2,stroke:#fb8c00,color:#e65100
```
